windows_stdio -

# 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

# `linker-flavor`

The tracking issue for this feature is: None

Every `rustc` target defaults to some linker. For example, Linux targets default to gcc. In some cases, you may want to override the default; you can do that with the unstable CLI argument: `-Z linker-flavor`.

Here how you would use this flag to link a Rust binary for the `thumbv7m-none-eabi` using LLD instead of GCC.

    $ xargo rustc --target thumbv7m-none-eabi -- \
        -C linker=ld.lld \
        -Z linker-flavor=ld \
        -Z print-link-args | tr ' ' '\n'
    "ld.lld"
    "-L"
    "$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
    "$PWD/target/thumbv7m-none-eabi/debug/deps/app-512e9dbf385f233c.0.o"
    "-o"
    "$PWD/target/thumbv7m-none-eabi/debug/deps/app-512e9dbf385f233c"
    "--gc-sections"
    "-L"
    "$PWD/target/thumbv7m-none-eabi/debug/deps"
    "-L"
    "$PWD/target/debug/deps"
    "-L"
    "$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
    "-Bstatic"
    "$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib/libcore-e1ccb7dfb1cb9ebb.rlib"
    "-Bdynamic"

Whereas the default is:

    $ xargo rustc --target thumbv7m-none-eabi -- \
        -C link-arg=-nostartfiles \
        -Z print-link-args | tr ' ' '\n'
    "arm-none-eabi-gcc"
    "-L"
    "$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
    "$PWD/target/thumbv7m-none-eabi/debug/deps/app-961e39416baa38d9.0.o"
    "-o"
    "$PWD/target/thumbv7m-none-eabi/debug/deps/app-961e39416baa38d9"
    "-Wl,--gc-sections"
    "-nodefaultlibs"
    "-L"
    "$PWD/target/thumbv7m-none-eabi/debug/deps"
    "-L"
    "$PWD/target/debug/deps"
    "-L"
    "$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib"
    "-Wl,-Bstatic"
    "$SYSROOT/lib/rustlib/thumbv7m-none-eabi/lib/libcore-e1ccb7dfb1cb9ebb.rlib"
    "-nostartfiles"
    "-Wl,-Bdynamic"

# `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.

# `remap-path-prefix`

The tracking issue for this feature is: #41555

The `-Z remap-path-prefix-from`, `-Z remap-path-prefix-to` commandline option pair allows to replace prefixes of any file paths the compiler emits in various places. This is useful for bringing debuginfo paths into a well-known form and for achieving reproducible builds independent of the directory the compiler was executed in. All paths emitted by the compiler are affected, including those in error messages.

In order to map all paths starting with `/home/foo/my-project/src` to `/sources/my-project`, one would invoke the compiler as follows:

    rustc -Zremap-path-prefix-from="/home/foo/my-project/src" -Zremap-path-prefix-to="/sources/my-project"

Debuginfo for code from the file `/home/foo/my-project/src/foo/mod.rs`, for example, would then point debuggers to `/sources/my-project/foo/mod.rs` instead of the original file.

The options can be specified multiple times when multiple prefixes should be mapped:

    rustc -Zremap-path-prefix-from="/home/foo/my-project/src" \
          -Zremap-path-prefix-to="/sources/my-project" \
          -Zremap-path-prefix-from="/home/foo/my-project/build-dir" \
          -Zremap-path-prefix-to="/stable-build-dir"

When the options are given multiple times, the nth `-from` will be matched up with the nth `-to` and they can appear anywhere on the commandline. Mappings specified later on the line will take precedence over earlier ones.

# Language features

# `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_sysv64`

The tracking issue for this feature is: #36167

# `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

# `advanced_slice_patterns`

The tracking issue for this feature is: #23121

See also `slice_patterns`.

The `advanced_slice_patterns` 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 identifier before the `..`, the result of the slice will be bound to that name. For example:

    #![feature(advanced_slice_patterns, 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));
    }

# `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: #42219

# `allow_internal_unstable`

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

# `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

# `attr_literals`

The tracking issue for this feature is: #34981

At present, literals are only accepted as the value of a key-value pair in attributes. What's more, only string literals are accepted. This means that literals can only appear in forms of `#[attr(name = "value")]` or `#[attr = "value"]`.

The `attr_literals` unstable feature allows other types of literals to be used in attributes. Here are some examples of attributes that can now be used with this feature enabled:

+`rust,ignore +#[attr] +#[attr(true)] +#[attr(ident)] +#[attr(ident, 100, true, "true", ident = 100, ident = "hello", ident(100))] +#[attr(100)] +#[attr(enabled = true)] +#[enabled(true)] +#[attr("hello")] +#[repr(C, align = 4)] +#[repr(C, align(4))]`

# `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: #27779

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;
    }

# `catch_expr`

The tracking issue for this feature is: #31436

The `catch_expr` feature adds support for a `catch` expression. The `catch` expression creates a new scope one can use the `?` operator in.

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

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

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

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

    #}

# `cfg_target_feature`

The tracking issue for this feature is: #29717

# `cfg_target_has_atomic`

The tracking issue for this feature is: #32976

# `cfg_target_thread_local`

The tracking issue for this feature is: #29594

# `cfg_target_vendor`

The tracking issue for this feature is: #29718

# `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);
    }

# `conservative_impl_trait`

The tracking issue for this feature is: #34511

The `conservative_impl_trait` feature allows a conservative form of abstract return types.

Abstract return types allow a function to hide a concrete return type behind a trait interface similar to trait objects, while still generating the same statically dispatched code as with concrete types.

## Examples

    #![feature(conservative_impl_trait)]

    fn even_iter() -> impl Iterator<Item=u32> {
        (0..).map(|n| n * 2)
    }

    fn main() {
        let first_four_even_numbers = even_iter().take(4).collect::<Vec<_>>();
        assert_eq!(first_four_even_numbers, vec![0, 2, 4, 6]);
    }

## Background

In today's Rust, you can write function signatures like:

    fn consume_iter_static<I: Iterator<Item=u8>>(iter: I) { }

    fn consume_iter_dynamic(iter: Box<Iterator<Item=u8>>) { }

In both cases, the function does not depend on the exact type of the argument. The type held is "abstract", and is assumed only to satisfy a trait bound.

- In the `_static` version using generics, each use of the function is specialized to a concrete, statically-known type, giving static dispatch, inline layout, and other performance wins.
- In the `_dynamic` version using trait objects, the concrete argument type is only known at runtime using a vtable.

On the other hand, while you can write:

    fn produce_iter_dynamic() -> Box<Iterator<Item=u8>> { }

...but you cannot write something like:

    fn produce_iter_static() -> Iterator<Item=u8> { }

That is, in today's Rust, abstract return types can only be written using trait objects, which can be a significant performance penalty. This RFC proposes "unboxed abstract types" as a way of achieving signatures like `produce_iter_static`. Like generics, unboxed abstract types guarantee static dispatch and inline data layout.

# `const_fn`

The tracking issue for this feature is: #24111

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_indexing`

The tracking issue for this feature is: #29947

The `const_indexing` feature allows the constant evaluation of index operations on constant arrays and repeat expressions.

## Examples

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

    #fn main() {
    const ARR: [usize; 5] = [1, 2, 3, 4, 5];
    const ARR2: [usize; ARR[1]] = [42, 99];

    #}

# `custom_attribute`

The tracking issue for this feature is: #29642

# `custom_derive`

The tracking issue for this feature is: #29644

# `decl_macro`

The tracking issue for this feature is: #39412

# `default_type_parameter_fallback`

The tracking issue for this feature is: #27336

# `drop_types_in_const`

The tracking issue for this feature is: #33156

# `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

# `fundamental`

The tracking issue for this feature is: #29635

# `generic_param_attrs`

The tracking issue for this feature is: #34761

# `global_allocator`

The tracking issue for this feature is: #27389

Rust programs may need to change the allocator that they're running with from time to time. This use case is distinct from an allocator-per-collection (e.g. a `Vec` with a custom allocator) and instead is more related to changing the global default allocator, e.g. what `Vec<T>` uses by default.

Currently Rust programs don't have a specified global allocator. The compiler may link to a version of jemalloc on some platforms, but this is not guaranteed. Libraries, however, like cdylibs and staticlibs are guaranteed to use the "system allocator" which means something like `malloc` on Unixes and `HeapAlloc` on Windows.

The `#[global_allocator]` attribute, however, allows configuring this choice. You can use this to implement a completely custom global allocator to route all default allocation requests to a custom object. Defined in RFC 1974 usage looks like:

    #![feature(global_allocator, allocator_api, heap_api)]

    use std::heap::{Alloc, System, Layout, AllocErr};

    struct MyAllocator;

    unsafe impl<'a> Alloc for &'a MyAllocator {
        unsafe fn alloc(&mut self, layout: Layout) -> Result<*mut u8, AllocErr> {
            System.alloc(layout)
        }

        unsafe fn dealloc(&mut self, ptr: *mut u8, layout: Layout) {
            System.dealloc(ptr, layout)
        }
    }

    #[global_allocator]
    static GLOBAL: MyAllocator = MyAllocator;

    fn main() {
        // This `Vec` will allocate memory through `GLOBAL` above
        let mut v = Vec::new();
        v.push(1);
    }

And that's it! The `#[global_allocator]` attribute is applied to a `static` which implements the `Alloc` trait in the `std::heap` module. Note, though, that the implementation is defined for `&MyAllocator`, not just `MyAllocator`. You may wish, however, to also provide `Alloc for MyAllocator` for other use cases.

A crate can only have one instance of `#[global_allocator]` and this instance may be loaded through a dependency. For example `#[global_allocator]` above could have been placed in one of the dependencies loaded through `extern crate`.

Note that `Alloc` itself is an `unsafe` trait, with much documentation on the trait itself about usage and for implementors. Extra care should be taken when implementing a global allocator as well as the allocator may be called from many portions of the standard library, such as the panicking routine. As a result it is highly recommended to not panic during allocation and work in as many situations with as few dependencies as possible as well.

# `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.

# `i128_type`

The tracking issue for this feature is: #35118

The `i128_type` feature adds support for 128 bit signed and unsigned integer types.

    #![feature(i128_type)]

    fn main() {
        assert_eq!(1u128 + 1u128, 2u128);
        assert_eq!(u128::min_value(), 0);
        assert_eq!(u128::max_value(), 340282366920938463463374607431768211455);

        assert_eq!(1i128 - 2i128, -1i128);
        assert_eq!(i128::min_value(), -170141183460469231731687303715884105728);
        assert_eq!(i128::max_value(), 170141183460469231731687303715884105727);
    }

# `inclusive_range_syntax`

The tracking issue for this feature is: #28237

To get a range that goes from 0 to 10 and includes the value 10, you can write `0...10`:

    #![feature(inclusive_range_syntax)]

    fn main() {
        for i in 0...10 {
            println!("{}", i);
        }
    }

# `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.

# `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;

    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 = "exchange_free"]
    unsafe fn deallocate(ptr: *mut u8, _size: usize, _align: usize) {
        libc::free(ptr as *mut libc::c_void)
    }

    #[lang = "box_free"]
    unsafe fn box_free<T: ?Sized>(ptr: *mut T) {
        deallocate(ptr as *mut u8, ::core::mem::size_of_val(&*ptr), ::core::mem::align_of_val(&*ptr));
    }

    #[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_fmt"] extern fn rust_begin_panic() -> ! { 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 `exchange_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;

    // 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_fmt"]
    #[no_mangle]
    pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
                                   _file: &'static str,
                                   _line: u32,
                                   _column: u32) -> ! {
        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;

    // 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_fmt"]
    #[no_mangle]
    pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
                                   _file: &'static str,
                                   _line: u32,
                                   _column: u32) -> ! {
        unsafe { intrinsics::abort() }
    }

## 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_fmt`, 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`.

# `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

# `log_syntax`

The tracking issue for this feature is: #29598

# `macro_reexport`

The tracking issue for this feature is: #29638

# `macro_vis_matcher`

The tracking issue for this feature is: #41022

With this feature gate enabled, the list of fragment specifiers gains one more entry:

- `vis`: a visibility qualifier. Examples: nothing (default visibility); `pub`; `pub(crate)`.

A `vis` variable may be followed by a comma, ident, type, or path.

# `main`

The tracking issue for this feature is: #29634

# `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

# `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: #28979

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;

    #}

# `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.

For example:

    #![feature(on_unimplemented)]

    #[rustc_on_unimplemented="a collection of type `{Self}` cannot be built from an \
                              iterator over elements of type `{A}`"]
    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][..]);
       |     ^^^^^^^^^^^^^ the trait `MyIterator<char>` is not implemented for `&[{integer}]`
       |
       = note: a collection of type `&[{integer}]` cannot be built from an iterator over elements of type `char`
       = note: required by `iterate_chars`

    error: aborting due to previous error

# `optin_builtin_traits`

The tracking issue for this feature is: #13231

# `overlapping_marker_traits`

The tracking issue for this feature is: #29864

# `panic_runtime`

The tracking issue for this feature is: #32837

# `placement_in_syntax`

The tracking issue for this feature is: #27779

# `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

Some of the macro debugging tips are applicable.

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.name.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.

# `prelude_import`

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

# `proc_macro`

The tracking issue for this feature is: #38356

This feature flag guards the new procedural macro features as laid out by RFC 1566, which alongside the now-stable custom derives, provide stabilizable alternatives to the compiler plugin API (which requires the use of perma-unstable internal APIs) for programmatically modifying Rust code at compile-time.

The two new procedural macro kinds are:

- Function-like procedural macros which are invoked like regular declarative macros, and:

- Attribute-like procedural macros which can be applied to any item which built-in attributes can be applied to, and which can take arguments in their invocation as well.

Additionally, this feature flag implicitly enables the `use_extern_macros` feature, which allows macros to be imported like any other item with `use` statements, as compared to applying `#[macro_use]` to an `extern crate` declaration. It is important to note that procedural macros may only be imported in this manner, and will throw an error otherwise.

You must declare the `proc_macro` feature in both the crate declaring these new procedural macro kinds as well as in any crates that use them.

### Common Concepts

As with custom derives, procedural macros may only be declared in crates of the `proc-macro` type, and must be public functions. No other public items may be declared in `proc-macro` crates, but private items are fine.

To declare your crate as a `proc-macro` crate, simply add:

    [lib]
    proc-macro = true

to your `Cargo.toml`.

Unlike custom derives, however, the name of the function implementing the procedural macro is used directly as the procedural macro's name, so choose carefully.

Additionally, both new kinds of procedural macros return a `TokenStream` which wholly replaces the original invocation and its input.

#### Importing

As referenced above, the new procedural macros are not meant to be imported via `#[macro_use]` and will throw an error if they are. Instead, they are meant to be imported like any other item in Rust, with `use` statements:

    #![feature(proc_macro)]

    // Where `my_proc_macros` is some crate of type `proc_macro`
    extern crate my_proc_macros;

    // And declares a `#[proc_macro] pub fn my_bang_macro()` at its root.
    use my_proc_macros::my_bang_macro;

    fn main() {
        println!("{}", my_bang_macro!());
    }

#### Error Reporting

Any panics in a procedural macro implementation will be caught by the compiler and turned into an error message pointing to the problematic invocation. Thus, it is important to make your panic messages as informative as possible: use `Option::expect` instead of `Option::unwrap` and `Result::expect` instead of `Result::unwrap`, and inform the user of the error condition as unambiguously as you can.

#### `TokenStream`

The `proc_macro::TokenStream` type is hardcoded into the signatures of procedural macro functions for both input and output. It is a wrapper around the compiler's internal representation for a given chunk of Rust code.

### Function-like Procedural Macros

These are procedural macros that are invoked like regular declarative macros. They are declared as public functions in crates of the `proc_macro` type and using the `#[proc_macro]` attribute. The name of the declared function becomes the name of the macro as it is to be imported and used. The function must be of the kind `fn(TokenStream) -> TokenStream` where the sole argument is the input to the macro and the return type is the macro's output.

This kind of macro can expand to anything that is valid for the context it is invoked in, including expressions and statements, as well as items.

Note: invocations of this kind of macro require a wrapping `[]`, `{}` or `()` like regular macros, but these do not appear in the input, only the tokens between them. The tokens between the braces do not need to be valid Rust syntax.

my_macro_crate/src/lib.rs

    #![feature(proc_macro)]

    // This is always necessary to get the `TokenStream` typedef.
    extern crate proc_macro;

    use proc_macro::TokenStream;

    #[proc_macro]
    pub fn say_hello(_input: TokenStream) -> TokenStream {
        // This macro will accept any input because it ignores it.
        // To enforce correctness in macros which don't take input,
        // you may want to add `assert!(_input.to_string().is_empty());`.
        "println!(\"Hello, world!\")".parse().unwrap()
    }

my_macro_user/Cargo.toml

    [dependencies]
    my_macro_crate = { path = "<relative path to my_macro_crate>" }

my_macro_user/src/lib.rs

    #![feature(proc_macro)]

    extern crate my_macro_crate;

    use my_macro_crate::say_hello;

    fn main() {
        say_hello!();
    }

As expected, this prints `Hello, world!`.

### Attribute-like Procedural Macros

These are arguably the most powerful flavor of procedural macro as they can be applied anywhere attributes are allowed.

They are declared as public functions in crates of the `proc-macro` type, using the `#[proc_macro_attribute]` attribute. The name of the function becomes the name of the attribute as it is to be imported and used. The function must be of the kind `fn(TokenStream, TokenStream) -> TokenStream` where:

The first argument represents any metadata for the attribute (see the reference chapter on attributes). Only the metadata itself will appear in this argument, for example:

- `#[my_macro]` will get an empty string.
- `#[my_macro = "string"]` will get `= "string"`.
- `#[my_macro(ident)]` will get `(ident)`.
- etc.

The second argument is the item that the attribute is applied to. It can be a function, a type definition, an impl block, an `extern` block, or a module—attribute invocations can take the inner form (`#![my_attr]`) or outer form (`#[my_attr]`).

The return type is the output of the macro which wholly replaces the item it was applied to. Thus, if your intention is to merely modify an item, it must be copied to the output. The output must be an item; expressions, statements and bare blocks are not allowed.

There is no restriction on how many items an attribute-like procedural macro can emit as long as they are valid in the given context.

my_macro_crate/src/lib.rs

    #![feature(proc_macro)]

    extern crate proc_macro;

    use proc_macro::TokenStream;

    /// Adds a `/// ### Panics` docstring to the end of the input's documentation
    ///
    /// Does not assert that its receiver is a function or method.
    #[proc_macro_attribute]
    pub fn panics_note(args: TokenStream, input: TokenStream) -> TokenStream {
        let args = args.to_string();
        let mut input = input.to_string();

        assert!(args.starts_with("= \""), "`#[panics_note]` requires an argument of the form \
                                           `#[panics_note = \"panic note here\"]`");

        // Get just the bare note string
        let panics_note = args.trim_matches(&['=', ' ', '"'][..]);

        // The input will include all docstrings regardless of where the attribute is placed,
        // so we need to find the last index before the start of the item
        let insert_idx = idx_after_last_docstring(&input);

        // And insert our `### Panics` note there so it always appears at the end of an item's docs
        input.insert_str(insert_idx, &format!("/// # Panics \n/// {}\n", panics_note));

        input.parse().unwrap()
    }

    // `proc-macro` crates can contain any kind of private item still
    fn idx_after_last_docstring(input: &str) -> usize {
        // Skip docstring lines to find the start of the item proper
        input.lines().skip_while(|line| line.trim_left().starts_with("///")).next()
            // Find the index of the first non-docstring line in the input
            // Note: assumes this exact line is unique in the input
            .and_then(|line_after| input.find(line_after))
            // No docstrings in the input
            .unwrap_or(0)
    }

my_macro_user/Cargo.toml

    [dependencies]
    my_macro_crate = { path = "<relative path to my_macro_crate>" }

my_macro_user/src/lib.rs

    #![feature(proc_macro)]

    extern crate my_macro_crate;

    use my_macro_crate::panics_note;

    /// Do the `foo` thing.
    #[panics_note = "Always."]
    pub fn foo() {
        panic!()
    }

Then the rendered documentation for `pub fn foo` will look like this:

> `pub fn foo()`

> Do the `foo` thing.

> # Panics

> Always.

# `profiler_runtime`

The tracking issue for this feature is: #42524.

# `quote`

The tracking issue for this feature is: #29601

# `repr_align`

The tracking issue for this feature is: #33626

# `repr_simd`

The tracking issue for this feature is: #27731

# `rustc_attrs`

The tracking issue for this feature is: #29642

# `rustc_diagnostic_macros`

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

# `rvalue_static_promotion`

The tracking issue for this feature is: #38865

The `rvalue_static_promotion` feature allows directly creating `'static` references to constant `rvalue`s, which in particular allowing for more concise code in the common case in which a `'static` reference is all that's needed.

## Examples

    #![feature(rvalue_static_promotion)]

    fn main() {
        let DEFAULT_VALUE: &'static u32 = &42;
        assert_eq!(*DEFAULT_VALUE, 42);
    }

# `sanitizer_runtime`

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

# `simd`

The tracking issue for this feature is: #27731

# `simd_ffi`

The tracking issue for this feature is: #27731

# `slice_patterns`

The tracking issue for this feature is: #23121

See also `advanced_slice_patterns`.

If you want to match against a slice or array, you can use `&` with the `slice_patterns` feature:

    #![feature(slice_patterns)]

    fn main() {
        let v = vec!["match_this", "1"];

        match &v[..] {
            &["match_this", second] => println!("The second element is {}", second),
            _ => {},
        }
    }

# `specialization`

The tracking issue for this feature is: #31844

# `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

# `target_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

# `type_ascription`

The tracking issue for this feature is: #23416

# `unboxed_closures`

The tracking issue for this feature is: #29625

# `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.

# `use_extern_macros`

The tracking issue for this feature is: #35896

# `used`

The tracking issue for this feature is: 40289.

The `#[used]` attribute can be applied to `static` variables to prevent the Rust compiler from optimizing them away even if they appear to be unused by the crate (appear to be "dead code").

    #![feature(used)]

    #[used]
    static FOO: i32 = 1;

    static BAR: i32 = 2;

    fn main() {}

If you compile this program into an object file, you'll see that `FOO` makes it to the object file but `BAR` doesn't. Neither static variable is used by the program.

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

    $ nm -C used.o
    0000000000000000 T main
                     U std::rt::lang_start
    0000000000000000 r used::FOO
    0000000000000000 t used::main

Note that the linker knows nothing about the `#[used]` attribute and will remove `#[used]` symbols if they are not referenced by other parts of the program:

    $ rustc -C opt-level=3 used.rs

    $ nm -C used | grep FOO

"This doesn't sound too useful then!" you may think but keep reading.

To preserve the symbols all the way to the final binary, you'll need the cooperation of the linker. Here's one example:

The ELF standard defines two special sections, `.init_array` and `.pre_init_array`, that may contain function pointers which will be executed before the `main` function is invoked. The linker will preserve symbols placed in these sections (at least when linking programs that target the `*-*-linux-*` targets).

    #![feature(used)]

    extern "C" fn before_main() {
        println!("Hello, world!");
    }

    #[link_section = ".init_array"]
    #[used]
    static INIT_ARRAY: [extern "C" fn(); 1] = [before_main];

    fn main() {}

So, `#[used]` and `#[link_section]` can be combined to obtain "life before main".

    $ rustc -C opt-level=3 before-main.rs

    $ ./before-main
    Hello, world!

Another example: ARM Cortex-M microcontrollers need their reset handler, a pointer to the function that will executed right after the microcontroller is turned on, to be placed near the start of their FLASH memory to boot properly.

This condition can be met using `#[used]` and `#[link_section]` plus a linker script.

    #![feature(lang_items)]
    #![feature(used)]
    #![no_main]
    #![no_std]

    extern "C" fn reset_handler() -> ! {
        loop {}
    }

    #[link_section = ".reset_handler"]
    #[used]
    static RESET_HANDLER: extern "C" fn() -> ! = reset_handler;

    #[lang = "panic_fmt"]
    fn panic_fmt() {}

    MEMORY
    {
      FLASH : ORIGIN = 0x08000000, LENGTH = 128K
      RAM : ORIGIN = 0x20000000, LENGTH = 20K
    }

    SECTIONS
    {
      .text ORIGIN(FLASH) :
      {
        /* Vector table */
        LONG(ORIGIN(RAM) + LENGTH(RAM)); /* initial SP value */
        KEEP(*(.reset_handler));

        /* Omitted: The rest of the vector table */

        *(.text.*);
      } > FLASH

      /DISCARD/ :
      {
        /* Unused unwinding stuff */
        *(.ARM.exidx.*)
      }
    }

    $ xargo rustc --target thumbv7m-none-eabi --release -- \
        -C link-arg=-Tlink.x -C link-arg=-nostartfiles

    $ arm-none-eabi-objdump -Cd target/thumbv7m-none-eabi/release/app
    ./target/thumbv7m-none-eabi/release/app:     file format elf32-littlearm

    Disassembly of section .text:

    08000000 <app::RESET_HANDLER-0x4>:
     8000000:       20005000        .word   0x20005000

    08000004 <app::RESET_HANDLER>:
     8000004:       08000009                                ....

    08000008 <app::reset_handler>:
     8000008:       e7fe            b.n     8000008 <app::reset_handler>

# Library Features

# `alloc`

The tracking issue for this feature is: #27783

# `alloc_jemalloc`

The tracking issue for this feature is: #33082

See also `alloc_system`.

The compiler currently ships two default allocators: `alloc_system` and `alloc_jemalloc` (some targets don't have jemalloc, however). These allocators are normal Rust crates and contain an implementation of the routines to allocate and deallocate memory. The standard library is not compiled assuming either one, and the compiler will decide which allocator is in use at compile-time depending on the type of output artifact being produced.

Binaries generated by the compiler will use `alloc_jemalloc` by default (where available). In this situation the compiler "controls the world" in the sense of it has power over the final link. Primarily this means that the allocator decision can be left up the compiler.

Dynamic and static libraries, however, will use `alloc_system` by default. Here Rust is typically a 'guest' in another application or another world where it cannot authoritatively decide what allocator is in use. As a result it resorts back to the standard APIs (e.g. `malloc` and `free`) for acquiring and releasing memory.

# Switching Allocators

Although the compiler's default choices may work most of the time, it's often necessary to tweak certain aspects. Overriding the compiler's decision about which allocator is in use is done simply by linking to the desired allocator:

    #![feature(alloc_system)]

    extern crate alloc_system;

    fn main() {
        let a = Box::new(4); // Allocates from the system allocator.
        println!("{}", a);
    }

In this example the binary generated will not link to jemalloc by default but instead use the system allocator. Conversely to generate a dynamic library which uses jemalloc by default one would write:

    #![feature(alloc_jemalloc)]
    #![crate_type = "dylib"]

    extern crate alloc_jemalloc;

    pub fn foo() {
        let a = Box::new(4); // Allocates from jemalloc.
        println!("{}", a);
    }
    # fn main() {}

# `alloc_system`

The tracking issue for this feature is: #33082

See also `alloc_jemalloc`.

The compiler currently ships two default allocators: `alloc_system` and `alloc_jemalloc` (some targets don't have jemalloc, however). These allocators are normal Rust crates and contain an implementation of the routines to allocate and deallocate memory. The standard library is not compiled assuming either one, and the compiler will decide which allocator is in use at compile-time depending on the type of output artifact being produced.

Binaries generated by the compiler will use `alloc_jemalloc` by default (where available). In this situation the compiler "controls the world" in the sense of it has power over the final link. Primarily this means that the allocator decision can be left up the compiler.

Dynamic and static libraries, however, will use `alloc_system` by default. Here Rust is typically a 'guest' in another application or another world where it cannot authoritatively decide what allocator is in use. As a result it resorts back to the standard APIs (e.g. `malloc` and `free`) for acquiring and releasing memory.

# Switching Allocators

Although the compiler's default choices may work most of the time, it's often necessary to tweak certain aspects. Overriding the compiler's decision about which allocator is in use is done simply by linking to the desired allocator:

    #![feature(alloc_system)]

    extern crate alloc_system;

    fn main() {
        let a = Box::new(4); // Allocates from the system allocator.
        println!("{}", a);
    }

In this example the binary generated will not link to jemalloc by default but instead use the system allocator. Conversely to generate a dynamic library which uses jemalloc by default one would write:

    #![feature(alloc_jemalloc)]
    #![crate_type = "dylib"]

    extern crate alloc_jemalloc;

    pub fn foo() {
        let a = Box::new(4); // Allocates from jemalloc.
        println!("{}", a);
    }
    # fn main() {}

# `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

# `ascii_ctype`

The tracking issue for this feature is: #39658

# `box_heap`

The tracking issue for this feature is: #27779

# `c_void_variant`

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

# `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

# `collection_placement`

The tracking issue for this feature is: #30172

# `collections`

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

# `collections_range`

The tracking issue for this feature is: #30877

# `compiler_fences`

The tracking issue for this feature is: #41091

The `compiler_fences` feature exposes the `compiler_fence` function in `std::sync::atomic`. This function is conceptually similar to C++'s `atomic_signal_fence`, which can currently only be accessed in nightly Rust using the `atomic_singlethreadfence_*` instrinsic functions in `core`, or through the mostly equivalent literal assembly:

    # #![allow(unused_variables)]
    #![feature(asm)]
    #fn main() {
    unsafe { asm!("" ::: "memory" : "volatile") };

    #}

A `compiler_fence` restricts the kinds of memory re-ordering the compiler is allowed to do. Specifically, depending on the given ordering semantics, the compiler may be disallowed from moving reads or writes from before or after the call to the other side of the call to `compiler_fence`. Note that it does not prevent the hardware from doing such re-ordering. This is not a problem in a single-threaded, execution context, but when other threads may modify memory at the same time, stronger synchronization primitives are required.

## Examples

`compiler_fence` is generally only useful for preventing a thread from racing with itself. That is, if a given thread is executing one piece of code, and is then interrupted, and starts executing code elsewhere (while still in the same thread, and conceptually still on the same core). In traditional programs, this can only occur when a signal handler is registered. In more low-level code, such situations can also arise when handling interrupts, when implementing green threads with pre-emption, etc.

To give a straightforward example of when a `compiler_fence` is necessary, consider the following example:

    # use std::sync::atomic::{AtomicBool, AtomicUsize};
    # use std::sync::atomic::{ATOMIC_BOOL_INIT, ATOMIC_USIZE_INIT};
    # use std::sync::atomic::Ordering;
    static IMPORTANT_VARIABLE: AtomicUsize = ATOMIC_USIZE_INIT;
    static IS_READY: AtomicBool = ATOMIC_BOOL_INIT;

    fn main() {
        IMPORTANT_VARIABLE.store(42, Ordering::Relaxed);
        IS_READY.store(true, Ordering::Relaxed);
    }

    fn signal_handler() {
        if IS_READY.load(Ordering::Relaxed) {
            assert_eq!(IMPORTANT_VARIABLE.load(Ordering::Relaxed), 42);
        }
    }

The way it is currently written, the `assert_eq!` is not guaranteed to succeed, despite everything happening in a single thread. To see why, remember that the compiler is free to swap the stores to `IMPORTANT_VARIABLE` and `IS_READ` since they are both `Ordering::Relaxed`. If it does, and the signal handler is invoked right after `IS_READY` is updated, then the signal handler will see `IS_READY=1`, but `IMPORTANT_VARIABLE=0`.

Using a `compiler_fence`, we can remedy this situation:

    #![feature(compiler_fences)]
    # use std::sync::atomic::{AtomicBool, AtomicUsize};
    # use std::sync::atomic::{ATOMIC_BOOL_INIT, ATOMIC_USIZE_INIT};
    # use std::sync::atomic::Ordering;
    use std::sync::atomic::compiler_fence;

    static IMPORTANT_VARIABLE: AtomicUsize = ATOMIC_USIZE_INIT;
    static IS_READY: AtomicBool = ATOMIC_BOOL_INIT;

    fn main() {
        IMPORTANT_VARIABLE.store(42, Ordering::Relaxed);
        // prevent earlier writes from being moved beyond this point
        compiler_fence(Ordering::Release);
        IS_READY.store(true, Ordering::Relaxed);
    }

    fn signal_handler() {
        if IS_READY.load(Ordering::Relaxed) {
            assert_eq!(IMPORTANT_VARIABLE.load(Ordering::Relaxed), 42);
        }
    }

A deeper discussion of compiler barriers with various re-ordering semantics (such as `Ordering::SeqCst`) is beyond the scope of this text. Curious readers are encouraged to read the Linux kernel's discussion of memory barriers, the C++ references on `std::memory_order` and `atomic_signal_fence`, and this StackOverflow answer for further details.

# `concat_idents_macro`

The tracking issue for this feature is: #29599

# `core_char_ext`

The tracking issue for this feature is: #32110

# `core_float`

The tracking issue for this feature is: #32110

# `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_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.

# `core_slice_ext`

The tracking issue for this feature is: #32110

# `core_str_ext`

The tracking issue for this feature is: #32110

# `dec2flt`

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

# `decode_utf8`

The tracking issue for this feature is: #33906

# `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.

# `discriminant_value`

The tracking issue for this feature is: #24263

# `error_type_id`

The tracking issue for this feature is: #27745

# `exact_size_is_empty`

The tracking issue for this feature is: #35428

# `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_flags_align`

The tracking issue for this feature is: #27726

# `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

# `fnbox`

The tracking issue for this feature is: #28796

# `from_utf8_error_as_bytes`

The tracking issue for this feature is: #40895

# `fused`

The tracking issue for this feature is: #35602

# `future_atomic_orderings`

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

# `get_type_id`

The tracking issue for this feature is: #27745

# `heap_api`

The tracking issue for this feature is: #27700

# `hint_core_should_pause`

The tracking issue for this feature is: #41196

Many programs have spin loops like the following:

    # #![allow(unused_variables)]
    #fn main() {
    use std::sync::atomic::{AtomicBool,Ordering};

    fn spin_loop(value: &AtomicBool) {
        loop {
            if value.load(Ordering::Acquire) {
                 break;
            }
        }
    }

    #}

These programs can be improved in performance like so:

    # #![allow(unused_variables)]
    #![feature(hint_core_should_pause)]
    #fn main() {
    use std::sync::atomic;
    use std::sync::atomic::{AtomicBool,Ordering};

    fn spin_loop(value: &AtomicBool) {
        loop {
            if value.load(Ordering::Acquire) {
                 break;
            }
            atomic::hint_core_should_pause();
        }
    }

    #}

Further improvements could combine `hint_core_should_pause` with exponential backoff or `std::thread::yield_now`.

# `i128`

The tracking issue for this feature is: #35118

# `inclusive_range`

The tracking issue for this feature is: #28237

# `int_error_internals`

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

# `integer_atomics`

The tracking issue for this feature is: #32976

# `io`

The tracking issue for this feature is: #27802

# `io_error_internals`

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

# `ip`

The tracking issue for this feature is: #27709

# `iter_rfind`

The tracking issue for this feature is: #39480

# `iterator_for_each`

The tracking issue for this feature is: #42986

To call a closure on each element of an iterator, you can use `for_each`:

    #![feature(iterator_for_each)]

    fn main() {
        (0..10).for_each(|i| println!("{}", i));
    }

# `iterator_step_by`

The tracking issue for this feature is: #27741

# `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

# `lookup_host`

The tracking issue for this feature is: #27705

# `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.

# `needs_drop`

The tracking issue for this feature is: #41890

# `never_type_impls`

The tracking issue for this feature is: #35121

# `nonzero`

The tracking issue for this feature is: #27730

# `offset_to`

The tracking issue for this feature is: #41079

# `once_poison`

The tracking issue for this feature is: #33577

# `ord_max_min`

The tracking issue for this feature is: #25663

# `panic_abort`

The tracking issue for this feature is: #32837

# `panic_col`

The tracking issue for this feature is: #42939

# `panic_unwind`

The tracking issue for this feature is: #32837

# `pattern`

The tracking issue for this feature is: #27721

# `placement_in`

The tracking issue for this feature is: #27779

# `placement_new_protocol`

The tracking issue for this feature is: #27779

# `print_internals`

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

# `proc_macro`

The tracking issue for this feature is: #38356

# `proc_macro_internals`

The tracking issue for this feature is: #27812

# `profiler_runtime_lib`

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

# `rand`

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

# `range_contains`

The tracking issue for this feature is: #32311

# `raw`

The tracking issue for this feature is: #27751

# `read_initializer`

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

# `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.

# `shared`

The tracking issue for this feature is: #27730

# `sip_hash_13`

The tracking issue for this feature is: #34767

# `slice_concat_ext`

The tracking issue for this feature is: #27747

# `slice_get_slice`

The tracking issue for this feature is: #35729

# `slice_rotate`

The tracking issue for this feature is: #41891

# `slice_rsplit`

The tracking issue for this feature is: #41020

The `slice_rsplit` feature enables two methods on slices: `slice.rsplit(predicate)` and `slice.rsplit_mut(predicate)`.

# `sort_internals`

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

# `splice`

The tracking issue for this feature is: #32310

The `splice()` method on `Vec` and `String` allows you to replace a range of values in a vector or string with another range of values, and returns the replaced values.

A simple example:

    # #![allow(unused_variables)]
    #![feature(splice)]
    #fn main() {
    let mut s = String::from("α is alpha, β is beta");
    let beta_offset = s.find('β').unwrap_or(s.len());

    // Replace the range up until the β from the string
    let t: String = s.splice(..beta_offset, "Α is capital alpha; ").collect();
    assert_eq!(t, "α is alpha, ");
    assert_eq!(s, "Α is capital alpha; β is beta");

    #}

# `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.

# `swap_nonoverlapping`

The tracking issue for this feature is: #42818

# `take_set_limit`

The tracking issue for this feature is: #42781

# `tcpstream_connect_timeout`

The tracking issue for this feature is: #43709

# `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_local_state`

The tracking issue for this feature is: #27716

# `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_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`

The tracking issue for this feature is: #27783

# `unique`

The tracking issue for this feature is: #27730

# `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

# `windows_c`

This feature is internal to the Rust compiler and is not 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.