rust-lang / rust-lang/rust-by-example

Unfortunate example in Lifetime Bounds chapter (15.4.6)

Open
#1,806 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Handlebars
Stars
8.1k
Forks
1.6k
PR merge metrics
No merged PRs in 30d

Description

The previous issue: #1686. Created a new one as suggested.

At time of writing the mentioned chapter can be found at this link.

Currently the example that illustrates the Trait + 'a bound looks as this:

use std::fmt::Debug; // Trait to bound with.

#[derive(Debug)]
struct Ref<'a, T: 'a>(&'a T);
// `Ref` contains a reference to a generic type `T` that has
// an unknown lifetime `'a`. `T` is bounded such that any
// *references* in `T` must outlive `'a`. Additionally, the lifetime
// of `Ref` may not exceed `'a`.

// A generic function which prints using the `Debug` trait.
fn print<T>(t: T) where
    T: Debug {
    println!("`print`: t is {:?}", t);
}

// Here a reference to `T` is taken where `T` implements
// `Debug` and all *references* in `T` outlive `'a`. In
// addition, `'a` must outlive the function.
fn print_ref<'a, T>(t: &'a T) where
    T: Debug + 'a {
//    T: Debug {// it is worked even in this case, so `+ 'a` part still stay unclear
    println!("`print_ref`: t is {:?}", t);
}

fn main() {
    let x = 7;
    let ref_x = Ref(&x);

    print_ref(&ref_x);
    print(ref_x);
}

However, as you can easely check, if you just remove + 'a bound the code is still valid. So for newbies it could be still unclear when they should use this construct. I think, that the example should not compile if such bound would be removed to show code that needs that feature.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Lifetime Bounds chapter (15.4.6) at the linked Rust by Example page and inspect the Trait + 'a example. Verify the behavior with and without the bound, then revise the example so removing + 'a makes it fail while retaining a clear explanation of when the bound is needed.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.