Rust RFCs

https://rust-lang.github.io/rfcs
Admin
A collection of Request For Comments (RFCs) that propose and document changes, features, and...
Tokens:676,796
Snippets:4,443
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Setup Project Directories and Crates

Source: https://rust-lang.github.io/rfcs/3662-mergeable-rustdoc-cross-crate-info

This snippet initializes the necessary directories for the documentation merging process and creates two Rust crates: 'trait-crate' defining a trait and 'struct-crate' defining a struct that implements the trait.

```bash
mkdir -p trait-crate/src struct-crate/src merged/doc
echo "pub trait Trait {}" > trait-crate/src/lib.rs
echo "pub struct Struct; impl trait-crate::Trait for Struct {}" > struct-crate/src/lib.rs
MERGED=file://$(realpath merged/doc)
```

--------------------------------

### Examples Section in API Documentation

Source: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions

Provides examples of how to structure the 'Examples' section in Rust API documentation, including demonstrating different ways to pass arguments to functions, such as strings or closures.

```markdown
/// # Examples
///
/// ```
/// use op;
///
/// let s = "foo";
/// let answer = op::compare(s, "bar");
/// ```
///
/// Passing a closure to compare with, rather than a string:
///
/// ```
/// use op;
///
/// let s = "foo";
/// let answer = op::compare(s, |a| a.chars().is_whitespace().all());
/// ```
```

--------------------------------

### Cargo Build Script Output Example

Source: https://rust-lang.github.io/rfcs/0403-cargo-build-command

This example shows the expected output format from a Rust build script to Cargo. Lines starting with `cargo:` are interpreted as metadata. The `rustc-flags` key specifies linker flags, while `root`, `libdir`, and `include` provide paths to library files and headers.

```rust
cargo:rustc-flags=-l static:foo -L /path/to/foo
cargo:root=/path/to/foo
cargo:libdir=/path/to/foo/lib
cargo:include=/path/to/foo/include

```

--------------------------------

### FOLLOW Set Examples Using Equality Relations

Source: https://rust-lang.github.io/rfcs/0550-macro-future-proofing

Provides examples of FOLLOW set computations for macro matchers, expressed as equality relations to abstract away the specifics of FOLLOW(NT). These examples show how FOLLOW sets are determined based on the structure of the macro matcher.

```rust
FOLLOW(`$( $d:ident $e:expr )*`) = FOLLOW(`$e:expr`)
FOLLOW(`$( $d:ident $e:expr )* $(;)*`) = FOLLOW(`$e:expr`) ∩ ANYTOKEN = FOLLOW(`$e:expr`)
FOLLOW(`$( $d:ident $e:expr )* $(;)* $( f |)+`) = ANYTOKEN
```

--------------------------------

### Cargo Install Command Usage

Source: https://rust-lang.github.io/rfcs/1200-cargo-install

Demonstrates the various ways to use the 'cargo install' command to install crates, manage installed crates, and specifies available options. This command facilitates sharing Rust code by allowing easy installation of binary crates.

```bash
Install a crate onto the local system

Installing new crates:
    cargo install [options]
    cargo install [options] [-p CRATE | --package CRATE] [--vers VERS]
    cargo install [options] --git URL [--branch BRANCH | --tag TAG | --rev SHA]
    cargo install [options] --path PATH

Managing installed crates:
    cargo install [options] --list

Options:
    -h, --help              Print this message
    -j N, --jobs N          The number of jobs to run in parallel
    --features FEATURES     Space-separated list of features to activate
    --no-default-features   Do not build the `default` feature
    --debug                 Build in debug mode instead of release mode
    --bin NAME              Only install the binary NAME
    --example EXAMPLE       Install the example EXAMPLE instead of binaries
    -p, --package CRATE     Install this crate from crates.io or select the
                            package in a repository/path to install.
    -v, --verbose           Use verbose output
    --root                  Directory to install packages into

This command manages Cargo's local set of install binary crates. Only packages
which have [[bin]] targets can be installed, and all binaries are installed into
`$HOME/.cargo/bin` by default (or `$CARGO_HOME/bin` if you change the home
directory).

There are multiple methods of installing a new crate onto the system. The
`cargo install` command with no arguments will install the current crate (as
specified by the current directory). Otherwise the `-p`, `--package`, `--git`,
and `--path` options all specify the source from which a crate is being
installed. The `-p` and `--package` options will download crates from crates.io.

Crates from crates.io can optionally specify the version they wish to install
via the `--vers` flags, and similarly packages from git repositories can
optionally specify the branch, tag, or revision that should be installed. If a
crate has multiple binaries, the `--bin` argument can selectively install only
one of them, and if you'd rather install examples the `--example` argument can
be used as well.

The `--list` option will list all installed packages (and their versions).
```

--------------------------------

### Rust Doc Comment Example Structure

Source: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions

Demonstrates the use of Markdown headings within Rust doc comments to structure documentation, with 'Examples' being a common top-level heading.

```rust
/// # Examples
///
/// ```rust
/// // Example code here
/// ```
```

--------------------------------

### Rust CI Job Configuration Example

Source: https://rust-lang.github.io/rfcs/3817-promote-aarch64-pc-windows-msvc-to-tier-1

Illustrates a potential configuration for a Rust CI job targeting 'aarch64-pc-windows-msvc'. This highlights the setup for building and testing Rust on Arm64 Windows runners.

```yaml
name: Rust Build and Test (aarch64-pc-windows-msvc)

jobs:
  build_and_test:
    runs-on: windows-11-arm
    steps:
    - name: Checkout code
      uses: actions/checkout@v3
    - name: Install Rust toolchain
      uses: actions-rs/toolchain@v1
      with:
        toolchain: stable
        target: aarch64-pc-windows-msvc
        override: true
    - name: Build Rust project
      run: cargo build --target aarch64-pc-windows-msvc
    - name: Run tests
      run: cargo test --target aarch64-pc-windows-msvc

```

--------------------------------

### Rust: `rustfix` Tool Example - Path Prefixes

Source: https://rust-lang.github.io/rfcs/2126-path-clarity

Conceptual example of how the `rustfix` tool might modify code to adhere to new linting rules. This specific example shows the addition of `crate::` prefixes to local paths.

```rust
// Original code (potentially triggering a lint):
// use my_module;

// Code after rustfix:
use crate::my_module;
```

--------------------------------

### Example of Filter::and usage in Rust

Source: https://rust-lang.github.io/rfcs/3123-rustdoc-scrape-examples

This code snippet demonstrates a practical example of using the `Filter::and` method in the Warp library. It showcases how to combine filters and map the results into a JSON response. This example is context-specific and aims to illustrate a real-world application.

```rust
let math = warp::path!("math" / u16);
let div_with_header = math
    .and(warp::get())
    .and(div_by())
    .map(|num: u16, denom: NonZeroU16| {
        warp::reply::json(&Math {
            op: format!("{} / {}", num, denom),
            output: num / denom.get(),
        })
    });
```

--------------------------------

### Rustdoc Command for Using Scraped Examples

Source: https://rust-lang.github.io/rfcs/3123-rustdoc-scrape-examples

Shows how `rustdoc` is invoked with the `--with-examples` flag, pointing to the generated JSON file. This allows rustdoc to incorporate the scraped example data during the documentation rendering process.

```bash
rustdoc --with-examples path/to/scraped_examples.json
```

--------------------------------

### Rust Global Allocator Setup Example

Source: https://rust-lang.github.io/rfcs/1974-global-allocators

Demonstrates how to set a global allocator in Rust using the `#[global_allocator]` attribute. This example assumes a custom allocator named `MyAllocator` is defined in the `my_allocator` crate.

```rust
extern crate my_allocator;

use my_allocator::{MyAllocator, MY_ALLOCATOR_INIT};

#[global_allocator]
static ALLOCATOR: MyAllocator = MY_ALLOCATOR_INIT;

fn main() {
    ...
}
```

--------------------------------

### Cargo.toml Workspace Configuration Examples

Source: https://rust-lang.github.io/rfcs/1525-cargo-workspace

Examples of Cargo.toml files demonstrating how to configure Rust workspaces for different project structures. This includes defining workspace members and specifying package workspaces.

```toml
# Example for a repository with Cargo.toml at the root
[workspace]

```

```toml
# Example for crates without a root crate
[workspace]
members = ["crate1", "crate2", "crate3"]

```

```toml
# Example for the first workspace (ws1)
[workspace]
members = ["crate1", "crate2"]

```

```toml
# Example for the second workspace (ws2) - no members specified
[workspace]

```

```toml
# Example for non-hierarchical workspaces (root/Cargo.toml)
[workspace]
members = ["../crates/crate1", "../crates/crate2"]

```

```toml
# Example for non-hierarchical workspaces (crates/crate1/Cargo.toml)
[package]
workspace = "../../root"

```

```toml
# Example for non-hierarchical workspaces (crates/crate2/Cargo.toml)
[package]
workspace = "../../root"

```

--------------------------------

### Rustdoc Implicit Main for Examples

Source: https://rust-lang.github.io/rfcs/3502-cargo-script

Discusses the potential for Rustdoc to support an implicit `main` function for code examples. This would unify the experience across the playground, rustdoc, and Cargo, allowing Cargo to run files directly.

```rust
/// ```
/// // Implicit main
/// println!("Hello, world!");
/// ```
```

--------------------------------

### Rust Jemalloc Allocator Implementation Example

Source: https://rust-lang.github.io/rfcs/1974-global-allocators

Provides an example structure for a `Jemalloc` allocator implementation in Rust, likely for integration with the `allocator` trait. This crate would be available on crates.io.

```rust
pub struct Jemalloc;

unsafe impl Allocator for Jemalloc {
    // ...
}

unsafe impl<'a> Allocator for &'a Jemalloc {
    // ...
}
```

--------------------------------

### Rustdoc Scrape Examples: JSON Output Format

Source: https://rust-lang.github.io/rfcs/3123-rustdoc-scrape-examples

Defines the structure of the JSON file generated by rustdoc, which maps functions to their call site locations within example code. This format is used to link specific functions to the examples where they are called.

```json
{
  "function_name": {
    "file": {
      "locations": [
        { "line": 10, "column": 5 },
        { "line": 12, "column": 8 }
      ],
      "other_metadata": "..."
    }
  }
}
```

--------------------------------

### Example Rust Crate for JSON Output

Source: https://rust-lang.github.io/rfcs/2963-rustdoc-json

This is an example of a simple Rust crate with crate-level documentation and functions/structs. When rustdoc is run with the `--output-format json` flag on this crate, it will produce a JSON file containing detailed information about its structure and documentation.

```rust
//! Here are some crate-level docs!

/// Here are some docs for `some_fn`!
pub fn some_fn() {}

/// Here are some docs for `SomeStruct`!
pub struct SomeStruct;
```

--------------------------------

### Cargo.toml Replace Directive Example

Source: https://rust-lang.github.io/rfcs/1969-cargo-prepublish

Shows an example of the older `[replace]` directive in Cargo.toml, which achieves a similar outcome to `[patch.crates-io]` by specifying an alternative source for a crate and version. The `[patch]` feature is considered more expressive and is recommended over `[replace]`.

```toml
[replace]
'log:0.3.7' = { git = 'https://github.com/rust-lang-nursery/log' }
```

--------------------------------

### WTF-8 Splitting Representation Example

Source: https://rust-lang.github.io/rfcs/2295-os-str-pattern

Provides a concrete example of how a 4-byte Unicode sequence is represented when split in WTF-8. It shows the byte sequences for the full character and its split high and low surrogate parts.

```text
"\u{10000}"      = f0 90 80 80
"\u{10000}"[..2] = f0 90 80
"\u{10000}"[2..] =    90 80 80
```

--------------------------------

### Rust Path Examples: Expression Paths

Source: https://rust-lang.github.io/rfcs/0195-associated-items

Provides illustrative examples of Rust expression paths, demonstrating how to reference functions within modules, generic functions, and associated functions of types or traits.

```rust
// Expression paths ///////////////////////////////////////////////////////////////

a::b::c         // reference to a function `c` in module `a::b`
a::<T1, T2>     // the function `a` instantiated with type arguments `T1`, `T2`
Vec::<T>::new   // reference to the function `new` associated with `Vec<T>`
<Vec<T> as SomeTrait>::some_fn
                // reference to the function `some_fn` associated with `SomeTrait`,
                //   as implemented by `Vec<T>`
T::size_of      // the function `size_of` associated with the type or trait `T`
<T>::size_of    // the function `size_of` associated with `T` _viewed as a type_
<T as SizeOf>::size_of
                // the function `size_of` associated with `T`'s impl of `SizeOf`
```

--------------------------------

### Hosted Environment lang_start Implementation (Rust)

Source: https://rust-lang.github.io/rfcs/1937-ques-in-main

The implementation of the generic `lang_start` for typical 'hosted' environments. It handles system initialization, thread setup, argument handling, panic catching, and process exit.

```rust
#[lang = "start"]
fn lang_start<T: Termination>
    (main: fn() -> T, argc: isize, argv: *const *const u8) -> !
{
    use panic;
    use sys;
    use sys_common;
    use sys_common::thread_info;
    use thread::Thread;

    sys::init();

    sys::process::exit(unsafe {
        let main_guard = sys::thread::guard::init();
        sys::stack_overflow::init();

        let thread = Thread::new(Some("main".to_owned()));
        thread_info::set(main_guard, thread);

        sys::args::init(argc, argv);

        let exitcode = panic::catch_unwind(|| main().report())
            .unwrap_or(101);

        sys_common::cleanup();
        exitcode
    });
}
```

--------------------------------

### Install and Setup Credential Process

Source: https://rust-lang.github.io/rfcs/3231-cargo-asymmetric-tokens

This demonstrates the workflow for registries that use hardware tokens for authentication. It involves installing a specific credential process helper, setting it up with the registry URL, and configuring `credentials.toml`.

```bash
cargo install credential-process-for-your-hardware-token
```

```bash
cargo credential-process-for-your-hardware-token setup registryURL
```

--------------------------------

### Cargo Uninstall Command Usage

Source: https://rust-lang.github.io/rfcs/1200-cargo-install

Demonstrates the command-line usage for uninstalling a locally installed Rust crate. It specifies options for targeting specific binaries or examples, and explains the role of the package identifier specification.

```text
Cargo won't remove the source for uninstalled crates, just the binaries that were installed by Cargo itself.
## 
Cargo will not currently attempt to manage anything other than a binary artifact of `cargo build`. For example the following items will not be available to installed crates:
  * Dynamic native libraries built as part of `cargo build`.
  * Native assets such as images not included in the binary itself.
  * The source code is not guaranteed to exist, and the binary doesn’t know where the source code is.

Additionally, Cargo will not immediately provide the ability to configure the installation stage of a package. There is often a desire for a “pre-install script” which runs various house-cleaning tasks. This is left as a future extension to Cargo.
# 
Beyond the standard “this is more surface area” and “this may want to aggressively include more features initially” concerns there are no known drawbacks at this time.
# 

```

--------------------------------

### Enabling rustdoc_scrape_examples feature

Source: https://rust-lang.github.io/rfcs/3123-rustdoc-scrape-examples

This command shows how to enable the `rustdoc_scrape_examples` feature when building documentation for a Rust project using Cargo. This flag instructs rustdoc to look for and include code examples from the project's `examples/` directory.

```bash
cargo doc --scrape-examples
```

--------------------------------

### Cargo: Create New Binary Project

Source: https://rust-lang.github.io/rfcs/3424-cargo-script

This command initializes a new Rust project with a standard directory structure for a binary application. It creates a `Cargo.toml` file for project metadata and a `src/main.rs` file for the main source code. The `--bin` flag specifies it's a binary, and `--vcs none` can be used to skip Git initialization.

```bash
$ cargo new hello_world --bin

```

--------------------------------

### Rust Path Examples

Source: https://rust-lang.github.io/rfcs/0132-ufcs

Illustrates valid path syntaxes based on the extended grammar, demonstrating how to invoke inherent, trait, and associated methods with varying levels of explicitness.

```rust
a::b::c
a::<T1,T2>::b::c
T::size_of
<T>::size_of
<T as SizeOf>::size_of
Eq::eq
Eq::<T>::eq
Zero::zero
```

--------------------------------

### Rust Compiler Error: Range not an Iterator

Source: https://rust-lang.github.io/rfcs/3550-new-range

An example of a Rust compiler error indicating that a `Range<usize>` is not an iterator, guiding users to convert it using `into_iter()` as per the new range type implementations.

```rust
error[E0599]: `Range<usize>` is not an iterator
 --> src/main.rs:4:7
  |
4 |     a.sum()
  |       ^^^ `Range<usize>` is not an iterator
  |
  = note: the Edition 2024 range types implement `IntoIterator`, not `Iterator`
  = help: convert to an iterator first: `a.into_iter().sum()`
  = note: the following trait bounds were not satisfied:
          `Range<usize>: Iterator`
```

--------------------------------

### Rust: Mutex Get Mut Example for Downgrade Pattern

Source: https://rust-lang.github.io/rfcs/2025-nested-method-calls

This example illustrates how `Mutex::get_mut` in Rust might be wrapped to showcase the 'downgrade-mut-to-shared' pattern. `get_mut` takes a mutable reference to the mutex and provides access to its interior without locking. This is only safe because it assumes the mutable borrow of `self` persists until the data is no longer used, highlighting a scenario where direct downgrading might be unsafe without further annotations.

```rust
// Hypothetical wrapper for Mutex::get_mut
// fn get_mut_and_return_shared(&mut self) -> &T {
//     // ... implementation that uses Mutex::get_mut internally
// }
```

--------------------------------

### TOML Lint Configuration Examples

Source: https://rust-lang.github.io/rfcs/3389-manifest-lint

Demonstrates several TOML syntaxes for specifying lints and their levels (warn, allow, deny). These examples highlight different approaches to structuring lint configurations, including using arrays of tables and nested tables. They primarily showcase configurations for `clippy` and `rust` lints.

```toml
[[lints.clippy]]
lint = "all"
level = "warn"
[[lints.clippy]]
lint = "cyclomatic_complexity"
level = "allow"
```

```toml
[tools.rust]
lints = [
    { warn = "all" },
    { allow = "allow_dead_code" },
    { deny = "unsafe_code" },
]
```

```toml
[lints.rust]
all = { level = "warn", priority = -1 }
allow_dead_code = "allow"
unsafe_code = "deny"
```

```toml
[lints.rust]
all = "warn"
allow_dead_code = "allow"
unsafe_code = "deny"
```

```toml
[lints.rust.groups]
all = "warn"
[lints.rust.lints]
allow_dead_code = "allow"
unsafe_code = "deny"
```

--------------------------------

### Rust Module with Private Field Observation Example

Source: https://rust-lang.github.io/rfcs/1445-restrict-constants-in-patterns

Defines a module `foo` with a struct `Foo` that has a private field `b` and public constants `V1` and `V2`. This setup is used to demonstrate how `match` can observe private fields, bypassing encapsulation.

```rust
mod foo {
    pub struct Foo { b: bool }
    pub const V1: Foo = Foo { b: true };
    pub const V2: Foo = Foo { b: false };
}
```

--------------------------------

### Bump Allocator Example using Rust Allocator Trait

Source: https://rust-lang.github.io/rfcs/1398-kinds-of-allocators

A simple, "super-dumb" bump allocator implementation demonstrating the usage of the Rust Allocator trait. This example serves as a basic illustration of how to create and use custom allocators.

```rust
use core::allocator::{Allocator, Layout};

struct BumpAllocator {
    memory: &'static mut [u8],
    next: usize,
}

impl BumpAllocator {
    const fn new(memory: &'static mut [u8]) -> Self {
        BumpAllocator { memory, next: 0 }
    }
}

unsafe impl Allocator for BumpAllocator {
    fn allocate(
        &mut self,
        layout: Layout,
    ) -> Result<core::ptr::NonNull<u8>, core::allocator::AllocError> {
        let start = self.memory.as_mut_ptr().add(self.next);
        let start = core::ptr::NonNull::new(start)?;

        let end = start.as_ptr().add(layout.size());
        if end.offset_from(self.memory.as_ptr()) > self.memory.len() as isize {
            return Err(core::allocator::AllocError);
        }

        self.next += layout.size();
        Ok(start)
    }

    unsafe fn deallocate(&mut self, ptr: core::ptr::NonNull<u8>, _layout: Layout) {
        // No-op: In a bump allocator, deallocation is not supported.
    }
}
```

--------------------------------

### Iterate f32 between 1.0 and 2.0 using next_up

Source: https://rust-lang.github.io/rfcs/3173-float-next-up-down

This example demonstrates how to iterate through f32 values starting from 1.0 up to and including 2.0 by repeatedly calling the `next_up()` method. This method is useful for testing functions with all values within a specific range.

```rust
let mut x = 1.0;
while x <= 2.0 {
    // test(x);
    x = x.next_up();
}
```

--------------------------------

### Rust Example: Using OsStr Methods and Slicing

Source: https://rust-lang.github.io/rfcs/2295-os-str-pattern

This example demonstrates the practical application of OsStr methods like `starts_with`, `ends_with`, and `rfind_range`, along with slicing capabilities. It simulates a Windows path to show how these functionalities can be used for path manipulation and string searching.

```rust
// (assume we are on Windows)

let path = OsStr::new(r"C:\\Users\\Admin\\😀\\😁😂😃😄.txt");
// can use starts_with, ends_with
assert!(path.starts_with(OsStr::new(r"C:\\")));
assert!(path.ends_with(OsStr::new(".txt"));
// can use rfind_range to get the range of substring
let last_backslash = path.rfind_range(OsStr::new(r"\")).unwrap();
assert_eq!(last_backslash, 16..17);
// can perform slicing.
let file_name = &path[last_backslash.end..];
```

--------------------------------

### Reference Items Using Crate-Relative Paths (Rust)

Source: https://rust-lang.github.io/rfcs/2126-path-clarity

Explains how to reference items within the current crate using crate-relative paths starting with `crate::`, `self`, or `super`. The example shows importing the `usage` module and calling its `print_usage` function.

```rust
use crate::cli::usage;

fn main() {
    // ...
    usage::print_usage()
    // ...
}

```

--------------------------------

### Usage Examples of the Enhanced `vec!` Macro in Rust

Source: https://rust-lang.github.io/rfcs/0832-from-elem-with-love

Provides example `main` function demonstrating the usage of the enhanced `vec!` macro in Rust, showcasing its ability to work with copy types, cloneable types, and runtime values for the count.

```rust
fn main() {
    println!("{:?}", vec![1; 10]);
    println!("{:?}", vec![Box::new(1); 10]);
    let n = 10;
    println!("{:?}", vec![1; n]);
}
```

--------------------------------

### Creating and Running a Simple Single-File Rust Program

Source: https://rust-lang.github.io/rfcs/3424-cargo-script

This example shows the basic process of creating a standalone Rust program in a single file and making it executable. It utilizes a shebang line for direct execution and demonstrates the 'Hello, world!' output. This is a fundamental example for understanding single-file Rust script execution.

```rust
#!/usr/bin/env cargo

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

```

--------------------------------

### Cargo build command examples

Source: https://rust-lang.github.io/rfcs/3127-trim-paths

Demonstrates basic Cargo build commands for release profiles, showcasing different configurations for path trimming and debug information.

```bash
Alice$ cargo build --release
```

```bash
Bob$ cargo build --release && perf record cargo run --release
```

```bash
Eve$ cargo build --release
```

```bash
Hana$ cargo build --release
```

--------------------------------

### Rust Async Closure Definition and Execution

Source: https://rust-lang.github.io/rfcs/2394-async_await

Illustrates the use of async closures in Rust. Similar to async functions, async closures return a `Future`. The example shows capturing a closure, calling it to get a future, and then executing that future using `futures::block_on`.

```rust
fn main() {
    let closure = async || {
         println!("Hello from async closure.");
    };
    println!("Hello from main");
    let future = closure();
    println!("Hello from main again");
    futures::block_on(future);
}
```

--------------------------------

### Macro Rules with Ambiguous Expression-Block Parsing

Source: https://rust-lang.github.io/rfcs/0550-macro-future-proofing

This macro_rules example demonstrates a scenario where the parser struggles to distinguish between a sequence of expressions and a block, leading to ambiguity. The parser cannot determine when to stop accepting expressions for `$foo` and start parsing the block for `$bar`, resulting in a 'local ambiguity' error.

```rust
macro_rules! foo {
    ($($foo:expr)* $bar:block) => (/*...*/)
};

```

--------------------------------

### Rust: Two-Phased Borrow Scenario with Vector Operations

Source: https://rust-lang.github.io/rfcs/2025-nested-method-calls

Presents a code example that would have been valid under a more expansive initial proposal for two-phased borrows, where all mutable borrows were converted. This scenario involves taking a mutable borrow of a vector, performing a read (getting its length), and then a write (pushing an element). This code would not type-check under the current RFC or existing rules.

```rust
let tmp0 = &mut vec;   // `vec` is reserved
let tmp1 = vec.len();  // shared borrow of vec; ok
Vec::push(tmp0, tmp1); // mutable borrow of `vec` is activated
```

--------------------------------

### Example Transformation by Test Framework Macro (Rust)

Source: https://rust-lang.github.io/rfcs/2318-custom-test-frameworks

Demonstrates how a procedural macro can transform annotated test functions into a runnable `main` function. It shows the input code with `#[test]` annotations and the resulting output code that sets up a runner and invokes tests.

```rust
#[test]
fn foo(x: u8) {
    // ...
}

mod bar {
    #[test]
    fn bar(x: String, y: u8) {
        // ...
    }
}

```

```rust
fn main() {
    // handles showing failures, etc
    let mut runner = quickcheck::Runner();

    runner.iter("foo", |random_source| foo(random_source.next().into()));
    runner.iter("bar::bar", |random_source| bar::bar(random_source.next().into(),
                                                     random_source.next().into()));
    runner.finish();
}

```

--------------------------------

### Windows File Sharing Mode Example

Source: https://rust-lang.github.io/rfcs/1252-open-options

Demonstrates how to set file sharing permissions on Windows using the `share_mode` method. This allows control over whether other processes can read, write, or delete the file. The example shows explicit granting of read, write, and delete access.

```rust
.share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)
```

--------------------------------

### Rust: Examples of match statement with leading '|'

Source: https://rust-lang.github.io/rfcs/1925-optional-match-vert

Provides illustrative examples of Rust code demonstrating the use of the proposed leading '|' in match statements. These examples showcase alternative patterns and code execution.

```rust
use Letter::*;

enum Letter {
    A,
    B,
    C,
    D,
}

fn main() {
    let a = Letter::A;
    let b = Letter::B;
    let c = Letter::C;
    let d = Letter::D;

    match a {
        A => "A",
        // Can do alternatives with a `|`.
        B | C | D => "B, C, or D",
    }

    match b {
        | A => "A",
        // Leading `|` is allowed.
        | B
        | C
        | D => "B, C, or D",
    }
}
```

--------------------------------

### Line Comments Example (Rust)

Source: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions

Demonstrates the preferred style for comments in Rust code, utilizing single-line comments (`//`) over block comments (`/* ... */`). This is a standard convention for code clarity.

```rust
// Wait for the main task to return, and set the process error code
// appropriately.
```

--------------------------------

### Execute Simple Hello World Rust Script

Source: https://rust-lang.github.io/rfcs/3502-cargo-script

This snippet shows a basic 'Hello, world!' program in a single Rust file that can be executed directly. After making the file executable, it can be run from the command line, and Cargo will compile and run it.

```rust
#!/usr/bin/env cargo

fn main() {
    println!("Hello, world!");
}
```

--------------------------------

### Starts With and Ends With

Source: https://rust-lang.github.io/rfcs/2500-needle

Checks if a string starts with or ends with a specified substring.

```APIDOC
## Starts With and Ends With

### Description
Checks if a string starts with or ends with a specified substring.

### Method
`starts_with<H, P>(haystack: H, needle: P) -> bool`
`ends_with<H, P>(haystack: H, needle: P) -> bool`

### Parameters
- **haystack** (Haystack) - The string to search within.
- **needle** (Needle<H>) - The substring to search for.

### Response
#### Success Response (200)
- **bool** - `true` if the string starts/ends with the needle, `false` otherwise.
```

--------------------------------

### Multi-language Code Snippet Formatting

Source: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions

Shows how to include code examples from different programming languages within Rust documentation, ensuring correct syntax highlighting for each.

```rust
```rust
println!("Hello, world!");
```
```

```ruby
puts "Hello"
```

--------------------------------

### Rust More Complex Method Call Example

Source: https://rust-lang.github.io/rfcs/2025-nested-method-calls

A more complex Rust method call example that demonstrates potential surprises due to nested method calls and argument evaluation order. This is presented as an example that might require a desugared explanation.

```rust
v[0].push_str(&format!("{}", v.len()))
```

--------------------------------

### Example Cargo.toml Dependency

Source: https://rust-lang.github.io/rfcs/3493-precise-pre-release-cargo-update

Defines a simple dependency in a `Cargo.toml` file. This serves as a baseline for demonstrating `cargo update` behavior with pre-release versions.

```toml
[dependencies]
example = "1.0.0"

```

--------------------------------

### Rust HashMap Example

Source: https://rust-lang.github.io/rfcs/3191-debugger-visualizer

A simple Rust program demonstrating the creation and population of a HashMap. This code serves as a basis for illustrating how a HashMap might appear in a debugger before and after applying visualizations.

```rust
use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 1);
    map.insert(2, 2);
    map.insert(3, 3);
}

```

--------------------------------

### Go Single-File Script Execution with gorun

Source: https://rust-lang.github.io/rfcs/3502-cargo-script

Introduces `gorun` as a tool to provide a scripting-like experience for Go. It allows building and running a single Go file, with automatic garbage collection for the build cache and project metadata specified in HEREDOCs.

```bash
gorun <file>
```

--------------------------------

### Well-Formedness (WF) Function Examples in Rust

Source: https://rust-lang.github.io/rfcs/0192-bounds-on-object-and-generic-types

Illustrates the 'T outlives 'a' relation and its definition through the WF function. These examples show how Rust checks if types are well-formed with respect to lifetime constraints, covering primitive types, references, nested references, and object types with static or explicit bounds.

```rust
// int always outlives any region
WF(int : 'a) = []

// a reference with lifetime 'a outlives 'b if 'a outlives 'b
WF(&'a int : 'b) = ['a : 'b]

// the outer reference must outlive 'c, and the inner reference
// must outlive the outer reference
WF(&'a &'b int : 'c) = ['a : 'c, 'b : 'a]

// Object type with bound 'static
WF(SomeTrait+'static : 'a) = ['static : 'a]

// Object type with bound 'a 
WF(SomeTrait+'a : 'b) = ['a : 'b]
```

--------------------------------

### File Structure: Standard Rust Project Layout

Source: https://rust-lang.github.io/rfcs/3424-cargo-script

This illustrates the conventional directory layout for a Rust project managed by Cargo. It outlines the placement of configuration files (`Cargo.toml`, `Cargo.lock`), source code (`src/`), libraries (`src/lib.rs`), executables (`src/main.rs`, `src/bin/`), benchmarks (`benches/`), examples (`examples/`), and tests (`tests/`).

```tree
.
├── Cargo.lock
├── Cargo.toml
└── src/
    ├── lib.rs
    ├── main.rs
    └── bin/
        ├── named-executable.rs
         ├── another-executable.rs
         └── multi-file-executable/
              ├── main.rs
              └── some_module.rs
├── benches/
│   ├── large-input.rs
│   └── multi-file-bench/
│       ├── main.rs
│       └── bench_module.rs
├── examples/
│   ├── simple.rs
│   └── multi-file-example/
│       ├── main.rs
│       └── ex_module.rs
└── tests/
    ├── some-integration-tests.rs
    └── multi-file-test/
        ├── main.rs
        └── test_module.rs

```

--------------------------------

### Trait Alias as a Bound Example

Source: https://rust-lang.github.io/rfcs/1733-trait-alias

A simple example demonstrating the use of a trait alias as a bound in a generic function signature.

```rust
trait StringIterator = Iterator<Item=String>;

fn iterate<SI>(si: SI) where SI: StringIterator {} // used as bound
```

--------------------------------

### RFC Implementation: Cfg Example

Source: https://rust-lang.github.io/rfcs/1559-attributes-with-literals

Shows another example of attribute simplification with `cfg` attributes, allowing numeric literals directly.

```rust
#[cfg(all(unix, target_pointer_width = "32"))] => #[cfg(all(unix, target_pointer_width = 32))]
```

--------------------------------

### OsString Find and Slice Example (Rust)

Source: https://rust-lang.github.io/rfcs/2295-os-str-pattern

Demonstrates the behavior of `OsString::find` and slicing with surrogate code points, highlighting potential incorrect results due to context-dependent index lengths.

```rust
__
let needle = OsString::from_wide(&[0xdc00]);
let haystack = OsStr::new("\u{10000}a");
let index = haystack.find(&needle).unwrap();
let matched = &haystack[index..(index + needle.len())];
// `matched` will contain "\u{dc00}a" instead of "\u{dc00}".

```

--------------------------------

### Ruby Enumerator and Fiber Examples

Source: https://rust-lang.github.io/rfcs/3513-gen-blocks

These Ruby examples illustrate generator-like behavior using `Enumerator` with `yield` for creating iterators and `Fiber` for general coroutines.

```ruby
def odd_dup_until_negative xs
  Enumerator.new do |y|
    xs.each do |x|
      if x < 0
        return
      elsif x % 2 == 1
        y.yield x * 2
      end
    end
  end
end

def dup
  Fiber.new do |x|
    while true
      x = Fiber.yield x * 2
    end
  end
end

g = dup
4 == (g.resume 2)
6 == (g.resume 3)
```

--------------------------------

### TOML: Basic Cargo.toml Package Configuration

Source: https://rust-lang.github.io/rfcs/3424-cargo-script

This snippet shows a minimal `Cargo.toml` file for a Rust package. It defines essential metadata such as the package name, version, and edition. The `[dependencies]` section is where external crates are listed, although it's empty in this basic example.

```toml
[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

[dependencies]


```

--------------------------------

### Alternative Vec Initialization Methods in Rust

Source: https://rust-lang.github.io/rfcs/0832-from-elem-with-love

Demonstrates various methods to initialize a `Vec` in Rust, highlighting their differences in verbosity, performance, and limitations compared to the proposed `vec![x; n]` sugar.

```rust
let vec = Vec::new();
for i in range(0, n) {
    vec.push(elem.clone())
}
```

```rust
let vec = vec![elem; n]
```

```rust
let vec = Vec::new();
vec.resize(elem, n);
```

```rust
let vec: Vec<_> = (0..n).map(|_| elem.clone()).collect()
```

```rust
let vec: Vec<_> = iter::repeat(elem).take(n).collect();
```

```rust
let vec = Vec::from_elem(elem, n)
```

--------------------------------

### Markdown Frontmatter Example

Source: https://rust-lang.github.io/rfcs/3503-frontmatter

A standard example of frontmatter syntax used in Markdown files, illustrating the metadata block typically found at the beginning of a document.

```markdown
---
name: My Blog Post
---

## Stuff happened

Hello world!
```

--------------------------------

### Rust cfg Attribute - Unsupported Literal Example

Source: https://rust-lang.github.io/rfcs/2523-cfg-path-version

Illustrates an example of an unsupported literal within a cfg attribute, resulting in a compiler error.

```Rust
// error[E0565]: unsupported literal
#[cfg(abracadabra(1.27))] fn bar() {}
                  ^^^^

```

--------------------------------

### Rust Box Destructuring Example

Source: https://rust-lang.github.io/rfcs/0059-remove-tilde

Demonstrates the destructuring form for the 'Box<T>' type using the 'box PAT' syntax. This example shows how to extract a value from a boxed expression.

```rust
let box(x) = box(10);
println!("{}", x); // prints 10
```

--------------------------------

### Slice is_sorted_by_key Method Examples

Source: https://rust-lang.github.io/rfcs/2351-is-sorted

Provides example usage of the `is_sorted_by_key` method for slices, demonstrating sorting based on string length and the absolute value of integers.

```rust
assert!(["c", "bb", "aaa"].is_sorted_by_key(|s| s.len()));
assert!(![-2i32, -1, 0, 3].is_sorted_by_key(|n| n.abs()));
```

--------------------------------

### Importing `alloc` Prelude and Specific Items in Rust

Source: https://rust-lang.github.io/rfcs/2480-liballoc

This example demonstrates how to import items from the `alloc` crate in a `no_std` Rust environment. It shows two methods: importing the entire prelude using `alloc::prelude::*`, or explicitly importing specific types like `ToString` and `Vec` from `alloc::string` and `alloc::vec` respectively.

```rust
use alloc::prelude::*;

// Or

use alloc::string::ToString;
use alloc::vec::Vec;
```

--------------------------------

### Rust CoerceUnsized Example Implementation for Rc

Source: https://rust-lang.github.io/rfcs/0982-dst-coercion

Provides an example implementation of the `CoerceUnsized` trait for `Rc<T>`, allowing `Rc<T>` to be coerced to `Rc<U>` if `T` is `Unsize<U>`.

```rust
impl<T: ?Sized+Unsize<U>, U: ?Sized> CoerceUnsized<Rc<U>> for Rc<T> {}
impl<T: Zeroable+CoerceUnsized<U>, U: Zeroable> CoerceUnsized<NonZero<U>> for NonZero<T> {}
```

--------------------------------

### Rust abstype Example: Scoped Existential Type

Source: https://rust-lang.github.io/rfcs/1951-expand-impl-trait

This example demonstrates the `abstype` keyword within a Rust module. It declares a public `abstype Token` implementing `Eq` and a function `fresh()` to generate new tokens. The key aspect is that outside the `example` module, the concrete type of `Token` (inferred as `u64` within the module) is opaque, preventing operations like addition.

```rust
mod example {
    use std::cell::Cell;

    static NEXT_TOKEN: Cell<u64> = Cell::new(0);

    pub abstype Token: Eq;
    pub fn fresh() -> Token {
        let r = NEXT_TOKEN.get();
        NEXT_TOKEN.set(r + 1);
        r
    }
}

fn main() {
    assert!(example::fresh() != example::fresh());

    // fails to compile, because in this scope we don't know that `Token` is `u64`
    // let _ = example::fresh() + 1;
}

```

--------------------------------

### Example Cargo Build Commands

Source: https://rust-lang.github.io/rfcs/2678-named-custom-cargo-profiles

These commands illustrate how to utilize custom Cargo profiles. It shows the standard build, a release build, and a build using the custom 'release-lto' profile. The output listing demonstrates how Cargo creates separate directories for each profile, including the custom one.

```bash
$ cargo build
$ cargo build --release
$ cargo build --profile release-lto
$ ls -l target
debug release release-lto
```

--------------------------------

### Rust: `if let` Chains Example

Source: https://rust-lang.github.io/rfcs/3137-let-else

Presents an example of `if let` chains, showcasing how multiple conditions involving pattern matching and boolean logic could be chained together.

```rust
if let Some(foo) = expr() && foo.is_baz() && let Ok(yay) = qux(foo) { ... }

```

--------------------------------

### FIRST Set Computation Examples for Macro Matchers

Source: https://rust-lang.github.io/rfcs/0550-macro-future-proofing

Demonstrates the computation of FIRST sets for different macro matchers. The FIRST set of a matcher is the set of tokens that can begin the sequence matched by that matcher. It shows how special elements like 'ε' (epsilon) are handled and how the sets are composed.

```rust
INPUT:  $(  $d:ident   $e:expr   );*    $( $( h )* );*    $( f ; )+   g
            ~~~~~~~~   ~~~~~~~                ~
                |         |                   |
FIRST:   { $d:ident }  { $e:expr }          { h }


INPUT:  $(  $d:ident   $e:expr   );*    $( $( h )* );*    $( f ; )+ 
            ~~~~~~~~~~~~~~~~~~             ~~~~~~~           ~~~
                       |                      |               |
FIRST:          { $d:ident }               { h, ε }         { f }


INPUT:  $(  $d:ident   $e:expr   );*    $( $( h )* );*    $( f ; )+   g
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~    ~~~~~~~~~~~~~~    ~~~~~~~~~   ~
                       |                       |              |       |
FIRST:        { $d:ident, ε }            {  h, ε, ;  }      { f }   { g }


INPUT:  $(  $d:ident   $e:expr   );*    $( $( h )* );*    $( f ; )+   g
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                                        |
FIRST:                       { $d:ident, h, ;,  f }

Thus:
  * FIRST(`$($d:ident $e:expr );* $( $(h)* );* $( f ;)+ g`) = { `$d:ident`, `h`, `;`, `f` }

Note however that:
  * FIRST(`$($d:ident $e:expr );* $( $(h)* );* $($( f ;)+ g)*`) = { `$d:ident`, `h`, `;`, `f`, ε }
```

--------------------------------

### Rust Async Stream Example with `IntoAsyncIterator`

Source: https://rust-lang.github.io/rfcs/2996-async-iterator

Provides an example implementation of `IntoAsyncIterator` for a custom type `S`. This demonstrates how to create an asynchronous stream of numbers using the `#[stream]` macro and `yield`.

```rust
type S(usize);

impl IntoAsyncIterator for S {
    type Item = usize;
    type IntoAsyncIterator: impl AsyncIterator<Item = Self::Item>;

    fn into_async_iter(self) -> Self::IntoAsyncIterator {
        #[stream]
        async move {
            for i in 0..self.0 {
                yield i;
            }
        }
    }
}
```

--------------------------------

### Rust `for` loop with `IntoIterator` Example

Source: https://rust-lang.github.io/rfcs/2996-async-iterator

Demonstrates a basic `for` loop iterating over a `Vec<i32>`, showcasing the usage of the `IntoIterator` trait. The example shows how a vector can be consumed to produce an iterator.

```rust
let values = vec![1, 2, 3, 4, 5];

for x in values {
    println!("{}", x);
}
```
Tokens:
Raw