Effective Rust

https://www.lurklurk.org/effective-rust
Admin
Effective Rust is a comprehensive guide providing 35 specific ways to improve your Rust code through...
Tokens:175,137
Snippets:1,146
Trust Score:9
Update:15 hours ago
Show doc for...
Tokens:
Raw
### Output of my_log! example

Source: https://www.lurklurk.org/effective-rust/macros.html

The output produced by the my_log! example, showing the file and line location and the formatted value.

```text
src/main.rs:331: x = 0x0a
```

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

### C header lib.h with FFI declarations

Source: https://www.lurklurk.org/effective-rust/bindgen.html

Example C header file (lib.h) containing a struct and two functions used to demonstrate bindgen input.

```c
/* File lib.h */
#include <stdint.h>

typedef struct {
    uint8_t byte;
    uint32_t integer;
} FfiStruct;

int add(int x, int y);
uint32_t add32(uint32_t x, uint32_t y);
```

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

### Rust unit test example with #[cfg(test)] and #[should_panic]

Source: https://www.lurklurk.org/effective-rust/testing.html

Shows a typical Rust unit test module with #[cfg(test)] attribute, #[test] functions, and a #[should_panic] test. The example includes a wildcard use super::* and uses assert_eq! and unwrap() for expected results. The #[should_panic] test exercises a function that panics on invalid input.

```rust
#![allow(unused)]
fn main() {
// ... (code defining `nat_subtract*` functions for natural
//      number subtraction)

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn test_nat_subtract() {
        assert_eq!(nat_subtract(4, 3).unwrap(), 1);
        assert_eq!(nat_subtract(4, 5), None);
    }

    #[should_panic]
    #[test]
    fn test_something_that_panics() {
        nat_subtract_unchecked(4, 5);
    }
}
}
```

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

### Output of log_failure! macro

Source: https://www.lurklurk.org/effective-rust/macros.html

Example output from the log_failure! macro showing the source file, line number, expression, and error details for the two failing calls.

```text
src/main.rs:340: operation '512.try_into()' failed: TryFromIntError(())
src/main.rs:341: operation 'std::str::from_utf8(b"\xc3\x28")' failed:
                 Utf8Error { valid_up_to: 0, error_len: Some(1) }
```

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

### Example output of TypeId printing

Source: https://www.lurklurk.org/effective-rust/reflection.html

Shows the output of the previous code snippet, displaying the TypeId values for x and y.

```text
x has TypeId { t: 18349839772473174998 }
y has TypeId { t: 2366424454607613595 }
```

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

### Stack frame reuse example in Rust

Source: https://www.lurklurk.org/effective-rust/lifetimes.html

Shows how stack frames are reused when different functions are called. The example defines a caller function that calls f and g, and the functions f and g use local variables. This illustrates the stack behavior described in the text.

```rust
#![allow(unused)]
fn main() {
fn caller() -> u64 {
    let x = 42u64;
    let y = 19u64;
    f(x) + g(y)
}

fn f(f_param: u64) -> u64 {
    let two = 2u64;
    f_param + two
}

fn g(g_param: u64) -> u64 {
    let arr = [2u64, 3u64];
    g_param + arr[1]
}
}
```

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

### C++ multithreaded usage of BankAccount

Source: https://www.lurklurk.org/effective-rust/deadlock.html

This code sets up a BankAccount and starts multiple threads: one that tops up the balance when low and three that repeatedly withdraw. This setup demonstrates how concurrent access can lead to data races.

```c++
BankAccount account;
account.deposit(1000);

// Start a thread that watches for a low balance and tops up the account.
std::thread payer(pay_in, &account);

// Start 3 threads that each try to repeatedly withdraw money.
std::thread taker(take_out, &account);
std::thread taker2(take_out, &account);
std::thread taker3(take_out, &account);
```

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

### Output of printing the input token stream

Source: https://www.lurklurk.org/effective-rust/macros.html

Shows the compile-time output of the macro implementation when invoked with the example arguments, displaying the token stream elements.

```text
Input TokenStream is:
  Literal { kind: Integer, symbol: "15", suffix: None,
            span: #0 bytes(10976..10978) }
  Punct { ch: ',', spacing: Alone, span: #0 bytes(10978..10979) }
  Ident { ident: "x", span: #0 bytes(10980..10981) }
  Punct { ch: '+', spacing: Alone, span: #0 bytes(10982..10983) }
  Ident { ident: "y", span: #0 bytes(10984..10985) }
  Punct { ch: ',', spacing: Alone, span: #0 bytes(10985..10986) }
  Ident { ident: "f32", span: #0 bytes(10987..10990) }
  Punct { ch: ':', spacing: Joint, span: #0 bytes(10990..10991) }
  Punct { ch: ':', spacing: Alone, span: #0 bytes(10991..10992) }
  Ident { ident: "consts", span: #0 bytes(10992..10998) }
  Punct { ch: ':', spacing: Joint, span: #0 bytes(10998..10999) }
  Punct { ch: ':', spacing: Alone, span: #0 bytes(10999..11000) }
  Ident { ident: "PI", span: #0 bytes(11000..11002) }
```

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

### Temporary expansion example: f((a + b) * 2)

Source: https://www.lurklurk.org/effective-rust/lifetimes.html

Shows an expression with temporaries and its roughly equivalent expanded form with explicit blocks and temporary variables.

```rust
let x = f((a + b) * 2);
```

```rust
let x = {
    let temp1 = a + b;
    {
        let temp2 = temp1 * 2;
        f(temp2)
    } // `temp2` dropped here
}; // `temp1` dropped here
```

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

### Using iter() method as start of iterator transformation

Source: https://www.lurklurk.org/effective-rust/iterators.html

Shows the equivalence between (&collection).into_iter().map(...) and collection.iter().map(...) for summing the inner u64 values.

```rust
let result: u64 = (&collection).into_iter().map(|thing| thing.0).sum();
```

```rust
let result: u64 = collection.iter().map(|thing| thing.0).sum();
```

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

### Truncated output showing the buggy behavior

Source: https://www.lurklurk.org/effective-rust/borrows.html

Shows the output of the previous example with a custom Debug implementation. It illustrates how the by_name map still points to old indices, causing incorrect lookups.

```text
Register starts as: {
  by_arrival: [{n: 'Alice', ...}, {n: 'Bob', ...}, {n: 'Charlie', ...}]
  by_name: {"Alice": 0, "Bob": 1, "Charlie": 2}
}
Register after deregister(0): {
  by_arrival: [{n: 'Bob', ...}, {n: 'Charlie', ...}]
  by_name: {"Alice": 0, "Bob": 1, "Charlie": 2}
}
Alice is Some(Guest { name: "Bob", address: "234 Bobton" })
Bob is Some(Guest { name: "Charlie", address: "345 Charlieland" })
Charlie is None
```

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

### Deref coercion example with Box<Point>

Source: https://www.lurklurk.org/effective-rust/references.html

Shows that a function expecting &Point can accept &Box<Point> due to Deref coercion. The output demonstrates the values printed for both a reference and a boxed point.

```rust
fn show(pt: &Point) {
    println!("({}, {})", pt.x, pt.y);
}
show(ref_pt);
show(&box_pt);
```

```text
(1, 2)
(10, 20)
```

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

### Thing type definition (non-Copy) for iterator examples

Source: https://www.lurklurk.org/effective-rust/iterators.html

Defines a Thing struct that deliberately does not implement Copy, to make ownership behavior explicit in the examples.

```rust
#![allow(unused)]
fn main() {
// Deliberately not `Copy`
#[derive(Clone, Debug, Eq, PartialEq)]
struct Thing(u64);

let collection = vec![Thing(0), Thing(1), Thing(2), Thing(3)];
}
```

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

### C: Output of immediate use

Source: https://www.lurklurk.org/effective-rust/lifetimes.html

Output showing the pointer and file descriptor when used immediately, which appears to work but is undefined behavior.

```text
in caller: file at 0x7ff7bc019408 has fd=3
```

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

### Lifetime subsumption example: smaller function

Source: https://www.lurklurk.org/effective-rust/lifetimes.html

Shows that the output lifetime must be subsumed within the smaller of the two input lifetimes. The example creates nested scopes and calls `smaller` with two `Item` references.

```rust
{
    let outer = Item { contents: 7 };
    {
        let inner = Item { contents: 8 };
        {
            let min = smaller(&inner, &outer);
            println!("smaller of {inner:?} and {outer:?} is {min:?}");
        } // `min` dropped
    } // `inner` dropped
} // `outer` dropped
```

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

### Create Any trait objects

Source: https://www.lurklurk.org/effective-rust/reflection.html

Creates Box<dyn Any> trait objects from a u64 and a Square instance, demonstrating how to build Any objects.

```rust
let x_any: Box<dyn Any> = Box::new(42u64);
let y_any: Box<dyn Any> = Box::new(Square::new(3, 4, 3));
```

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

### Importing from a prelude module

Source: https://www.lurklurk.org/effective-rust/wildcard.html

Shows the convention of importing from a crate's prelude module, which is explicitly intended for wildcard imports.

```rust
use thing::prelude::*;
```

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

### Lossless conversion with `as` and `into`

Source: https://www.lurklurk.org/effective-rust/casts.html

Shows converting a `u32` to `u64` using both `as` and `into()`. The `as` version is explicit, while `into()` is the idiomatic alternative.

```rust
#![allow(unused)]
fn main() {
let x: u32 = 9;
let y = x as u64;
let z: u64 = x.into();
}
```

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

### Output from running cargo fuzz run target1

Source: https://www.lurklurk.org/effective-rust/testing.html

Example output from `cargo +nightly fuzz run target1` showing the fuzzer initialization and the panic that occurs due to the out-of-bounds index in `is_fuzz`. The panic message indicates the index is 3 but the length is 3, and the stack trace points to the `is_fuzz` function.

```text
INFO: Running with entropic power schedule (0xFF, 100).
INFO: Seed: 1607525774
INFO: Loaded 1 modules: 1624 [0x108219fa0, 0x10821a5f8),
INFO: Loaded 1 PC tables (1624 PCs): 1624 [0x10821a5f8,0x108220b78),
INFO:        9 files found in fuzz/corpus/target1
INFO: seed corpus: files: 9 min: 1b max: 8b total: 46b rss: 38Mb
#10	INITED cov: 26 ft: 26 corp: 6/22b exec/s: 0 rss: 39Mb
thread panicked at 'index out of bounds: the len is 3 but the index is 3',
     testing/src/lib.rs:77:12
stack backtrace:
   0: rust_begin_unwind
             at /rustc/f77bfb7336f2/library/std/src/panicking.rs:579:5
   1: core::panicking::panic_fmt
             at /rustc/f77bfb7336f2/library/core/src/panicking.rs:64:14
   2: core::panicking::panic_bounds_check
             at /rustc/f77bfb7336f2/library/core/src/panicking.rs:159:5
   3: somecrate::is_fuzz
   4: _rust_fuzzer_test_input
   5: ___rust_try
   6: _LLVMFuzzerTestOneInput
   7: __ZN6fuzzer6Fuzzer15ExecuteCallbackEPKhm
   8: __ZN6fuzzer6Fuzzer6RunOneEPKhmbPNS_9InputInfoEbPb
   9: __ZN6fuzzer6Fuzzer16MutateAndTestOneEv
  10: __ZN6fuzzer6Fuzzer4LoopERNSt3__16vectorINS_9SizedFileENS_
      16fuzzer_allocatorIS3_EEEE
  11: __ZN6fuzzer12FuzzerDriverEPiPPPcPFiPKhmE
  12: _main
```

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

### Function that panics on invalid input

Source: https://www.lurklurk.org/effective-rust/panic.html

Shows a divide function that panics when the divisor is zero. This is the starting point for the discussion on panic handling.

```rust
#![allow(unused)]
fn main() {
fn divide(a: i64, b: i64) -> i64 {
    if b == 0 {
        panic!("Cowardly refusing to divide by zero!");
    }
    a / b
}
}
```

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

### Manual struct initialization with optional fields

Source: https://www.lurklurk.org/effective-rust/builders.html

Shows the verbose way to initialize a struct with optional fields, requiring explicit None for each optional field. This is brittle because adding a field requires updating all construction sites.

```rust
#![allow(unused)]
fn main() {
/// Phone number in E164 format.
#[derive(Debug, Clone)]
pub struct PhoneNumberE164(pub String);

#[derive(Debug, Default)]
pub struct Details {
    pub given_name: String,
    pub preferred_name: Option<String>,
    pub middle_name: Option<String>,
    pub family_name: String,
    pub mobile_phone: Option<PhoneNumberE164>,
}

// ...

let dizzy = Details {
    given_name: "Dizzy".to_owned(),
    preferred_name: None,
    middle_name: None,
    family_name: "Mixer".to_owned(),
    mobile_phone: None,
};
}

```

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

### Item struct definition

Source: https://www.lurklurk.org/effective-rust/lifetimes.html

Defines a public struct Item with a u32 field, used in subsequent examples. Includes derive attributes for Debug and Clone.

```rust
#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
/// Definition of an item of some kind.
pub struct Item {
    contents: u32,
}
}
```

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

### C++ pay_in and take_out thread functions

Source: https://www.lurklurk.org/effective-rust/deadlock.html

These functions are used by the threads in the previous example. pay_in monitors the balance and deposits when low, while take_out repeatedly attempts withdrawals. The infinite loops with sleeps are for demonstration purposes.

```c++
// Constantly monitor the `account` balance and top it up if low.
void pay_in(BankAccount* account) {
  while (true) {
    if (account->balance() < 200) {
      log("[A] Balance running low, deposit 400");
      account->deposit(400);
    }
    // (The infinite loop with sleeps is just for demonstration/simulation
    // purposes.)
    std::this_thread::sleep_for(std::chrono::milliseconds(5));
  }
}

// Repeatedly try to perform withdrawals from the `account`.
void take_out(BankAccount* account) {
  while (true) {
    if (account->withdraw(100)) {
      log("[B] Withdrew 100, balance now " +
          std::to_string(account->balance()));
    } else {
      log("[B] Failed to withdraw 100");
    }
    std::this_thread::sleep_for(std::chrono::milliseconds(20));
  }
}
```

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

### Manual initialization without Default

Source: https://www.lurklurk.org/effective-rust/builders.html

Shows the verbose manual initialization required when a field type does not implement Default, filling in all fields explicitly.

```rust
let bob = Details {
    given_name: "Robert".to_owned(),
    preferred_name: Some("Bob".to_owned()),
    middle_name: Some("the".to_owned()),
    family_name: "Builder".to_owned(),
    mobile_phone: None,
    date_of_birth: time::Date::from_calendar_date(
        1998,
        time::Month::November,
        28,
    )
    .unwrap(),
    last_seen: None,
};
```

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

### Output after deregister(0)

Source: https://www.lurklurk.org/effective-rust/borrows.html

Shows the state of the collections after deregistering index 0: Alice is removed, Bob and Charlie remain. The output is from the example code.

```text
Register after deregister(0): {
  by_arrival: [{n: 'Bob', ...}, {n: 'Charlie', ...}]
  by_name: [("Bob", {n: 'Bob', ...}), ("Charlie", {n: 'Charlie', ...})]
}
Alice is None
Bob is Some(RefCell { value: Guest { name: "Bob",
                                     address: "234 Bobton" } })
Charlie is Some(RefCell { value: Guest { name: "Charlie",
                                         address: "345 Charlieland" } })
```

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

### GameServer struct with Mutex-protected maps

Source: https://www.lurklurk.org/effective-rust/deadlock.html

Defines a GameServer with players and games maps, each protected by a Mutex. This is the core data structure used in the deadlock examples.

```rust
struct GameServer {
    // Map player name to player info.
    players: Mutex<HashMap<String, Player>>,
    // Current games, indexed by unique game ID.
    games: Mutex<HashMap<GameId, Game>>,
}
```

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

### C++ dangling reference example

Source: https://www.lurklurk.org/effective-rust/references.html

Shows a C++ function returning a reference to a local stack variable, which is a dangling reference footgun because C++ has no lifetime checks.

```c++
// C++
const int& dangle() {
  int x = 32; // on the stack, overwritten later
  return x; // return reference to stack variable!
}
```

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

### Lossy conversion with `as`

Source: https://www.lurklurk.org/effective-rust/casts.html

Demonstrates a lossy conversion from `u32` to `u16` using `as`, which is allowed but would be rejected by `from`/`into`.

```rust
#![allow(unused)]
fn main() {
let x: u32 = 9;
let y = x as u16;
}
```

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

### Runtime panic output from unwrap()

Source: https://www.lurklurk.org/effective-rust/iterators.html

Shows the panic message produced when the `unwrap()` example encounters the out-of-range value. The error is `TryFromIntError(())` and the panic occurs at `iterators/src/main.rs:266:36`.

```text
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value:
TryFromIntError(())', iterators/src/main.rs:266:36
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```

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

### RefCell borrow example

Source: https://www.lurklurk.org/effective-rust/references.html

Creates a RefCell<u64> with value 42 and takes two immutable borrows. Borrowing is checked at runtime; using borrow() can panic if the borrow rules are violated, while try_borrow() returns a Result.

```rust
#![allow(unused)]
fn main() {
use std::cell::RefCell;
let rc: RefCell<u64> = RefCell::new(42);
let b1 = rc.borrow();
let b2 = rc.borrow();
}
```

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

### Define InputData struct with optional payload

Source: https://www.lurklurk.org/effective-rust/transform.html

Defines a struct InputData with an optional Vec<u8> payload. Used as the context for the subsequent examples about transforming Option references.

```rust
#![allow(unused)]
fn main() {
struct InputData {
    payload: Option<Vec<u8>>,
}
}
```

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

### Rust: GuestRegister with cloned data for name lookup

Source: https://www.lurklurk.org/effective-rust/borrows.html

Implements a GuestRegister that clones Guest data into a BTreeMap for name-based lookup. Requires Guest to be Clone and is suitable for small, immutable data.

```rust
mod cloned {
    use super::Guest;

    #[derive(Default, Debug)]
    pub struct GuestRegister {
        by_arrival: Vec<Guest>,
        by_name: std::collections::BTreeMap<String, Guest>,
    }

    impl GuestRegister {
        pub fn register(&mut self, guest: Guest) {
            // Requires `Guest` to be `Clone`
            self.by_arrival.push(guest.clone());
            // Not checking for duplicate names to keep this
            // example shorter.
            self.by_name.insert(guest.name.clone(), guest);
        }
        pub fn named(&self, name: &str) -> Option<&Guest> {
            self.by_name.get(name)
        }
        pub fn nth(&self, idx: usize) -> Option<&Guest> {
            self.by_arrival.get(idx)
        }
    }
}
```

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

### Define a simple trait Calculate

Source: https://www.lurklurk.org/effective-rust/references.html

Defines a trait named Calculate with add and mul methods. The #![allow(unused)] and fn main() are typical for Rust documentation examples.

```rust
#![allow(unused)]
fn main() {
trait Calculate {
    fn add(&self, l: u64, r: u64) -> u64;
    fn mul(&self, l: u64, r: u64) -> u64;
}
}
```

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

### Joining thruster and trajectory functions with .into()

Source: https://www.lurklurk.org/effective-rust/newtype.html

Shows the corrected call site using .into() to convert PoundForceSeconds to NewtonSeconds, leveraging the From implementation.

```rust
let thruster_force: PoundForceSeconds = thruster_impulse(direction);
let new_direction = update_trajectory(thruster_force.into());
```

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

### Input vector causing runtime failure

Source: https://www.lurklurk.org/effective-rust/iterators.html

Defines an input vector containing a value (512) that does not fit into `u8`, causing the previous `unwrap()` example to panic at runtime.

```rust
#![allow(unused)]
fn main() {
let inputs: Vec<i64> = vec![0, 1, 2, 3, 4, 512];
}
```

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

### Rust: Guest struct and GuestRegister with owned data

Source: https://www.lurklurk.org/effective-rust/borrows.html

Defines a Guest struct and a GuestRegister that owns a Vec<Guest>. This is the base data structure used in the following examples.

```rust
#![allow(unused)]
fn main() {
#[derive(Clone, Debug)]
pub struct Guest {
    name: String,
    address: String,
    // ... many other fields
}

/// Local error type, used later.
#[derive(Clone, Debug)]
pub struct Error(String);

/// Register of guests recorded in order of arrival.
#[derive(Default, Debug)]
pub struct GuestRegister(Vec<Guest>);

impl GuestRegister {
    pub fn register(&mut self, guest: Guest) {
        self.0.push(guest)
    }
    pub fn nth(&self, idx: usize) -> Option<&Guest> {
        self.0.get(idx)
    }
}
}
```

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

### Using Vec::try_reserve for fallible allocation

Source: https://www.lurklurk.org/effective-rust/no-std.html

Demonstrates a fallible approach to building a Vec by using try_reserve to pre-allocate, then pushing without allocation failures.

```rust
#![allow(unused)]
fn main() {
fn try_build_a_vec() -> Result<Vec<u8>, String> {
    let mut v = Vec::new();

    // Perform a careful calculation to figure out how much space is needed,
    // here simplified to...
    let required_size = 4;

    v.try_reserve(required_size)
        .map_err(|_e| format!("Failed to allocate {} items!", required_size))?;

    // We now know that it's safe to do:
    v.push(1);
    v.push(2);
    v.push(3);
    v.push(4);

    Ok(v)
}
}
```
Tokens:
Raw