Document how `use path::Trait;` pulls impls into scope

[seanmonstar]

Our documentation on this matter is pretty poor; we need at a minimum to:

• Document this particular case of use declaration
• Write a small example pulling a trait from another mod
• Put cross-references to the new section as appropriate (from the sections on use and on Traits, at a minimum).

Original bug report follows

---

Original title: "error "does not implement any method in scope named" if trait is not imported into mod"

I have a struct that implements a trait, and then an other module (the test module) that uses my struct. I get a compiler error when calling a method from that trait, unless I also use the trait.

Test Code:

mod foo {
  pub trait Foo {
    fn foo(&self) {

    }
  }
}

mod bar {
  use foo::Foo;

  pub struct Bar;
  impl Foo for Bar {
    fn foo(&self) {
      println!("foobar!");
    }
  }

  #[cfg(test)]
  mod tests {
    use super::Bar;
    //use foo::Foo; // uncomment this means no error

    #[test]
    fn foobar() {
      let bar = Bar;
      bar.foo();
    }
  }
}

Ouput of rustc -v:

D:\Program Files (x86)\Rust\bin\rustc.exe 0.9 (7613b15 2014-01-08 18:04:43 -0800)
host: i686-pc-mingw32

[pnkfelix]

This is by design. (i am looking in the manual now so I can provide a link to the discussion there.)

[pnkfelix]

The discussion of this matter in the manual is pretty impoverished. Its pretty easy to overlook this sentence from the 0.9 manual:

• "All values that have implementations of this trait in scope can have their draw and bounding_box methods called" (emphasis added).

And worse, I did not see any examples in the manual showing how to write use Trait; to pull the implementations of that trait into scope. (Such discussion would need to come after both traits and modules have been introduced, but that's okay; we can have forward references from those sections as well as the section on use declarations.)

[pnkfelix]

@seanmonstar updated the bug description to reflect what I think the real bug here is, namely one of documentation; I left all your original text at the bottom of the description for posterity. Feel free to ask questions or revise as needed.

[seanmonstar]

I was further confused how the docs for HashMap only show use std::hashmap::HashMap, and never importing Container.

[pnkfelix]

@seanmonstar do they ever call any of the Container methods? It does not seem so AFAICT.

[seanmonstar]

Yea, they call hashmap.insert() which comes from the Container trait.
On Jan 20, 2014 1:32 PM, "Felix S Klock II" notifications@github.com
wrote:

@seanmonstar https://github.com/seanmonstar do they ever call any of
the Container methods? It does not seem so AFAICT.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/11690#issuecomment-32799044
.

[seanmonstar]

Sorry, insert is from MutableMap from the container module:
http://static.rust-lang.org/doc/master/std/container/trait.MutableSet.html

Here's docs from the hashmap module that don't include using the trait:
http://static.rust-lang.org/doc/master/std/hashmap/index.html

[huonw]

There is a special 'prelude' module in libstd (std::prelude) that contains reexports of various traits (including Container). This module is used at the top of every module so all those traits and their methods are always in scope.

[seanmonstar]

So then, what's the reasoning for the design of this? It seems like std classes feel nice to use, but if I design a library with a few traits, and implement a struct on them, that I'll need to use several traits as well to use my struct.

[pnkfelix]

@seanmonstar I believe the motivation is to force you to pull the relevant subset of all implemented traits (at least all implemented for the receiver type) into scope, in order to resolve potential name collisions eagerly.

(The main alternative I can think of is to treat all implementations of the receiver type as already in scope, and then when name collisions arise, tell the user to go resolve the conflict in some manner. Such as by adding explicit use declarations much like the ones we are making you put in now.)

Note that requiring the use declarations up front (rather than waiting for a name collision to arise somewhere down the line in the software development cycle) should make the code in your crate more robust to future changes in other modules within the crate.

This is sort-of analogous to requiring trait bounds on type parameters that build up the set of methods available for you to call on them, rather than delaying the check for whether the methods are present to the point where all of the types are fully instantiated, and only then providing an error message.

(Hypothetically there might be advantages also for the performance of the compiler, but that's just a theoretical musing on my part, and its irrelevant for the short-term since rustc is slow right now. For the long term, though, that might be a different story.)

At least, that's my take on it. I suspect others may see it otherwise.

Also, I put an entry for this question onto the flourishing Design FAQ ticket

[steveklabnik]

I've mentioned this behaviour in the Guide.

[steveklabnik]

Given that this is discussed in the Guide, I'm closing.