Rust use vs mod?

Question

I'm struggling to wrap my head around these,

• use declaration

  A use declaration creates one or more local name bindings synonymous with some other path. Usually, a use declaration is used to shorten the path required to refer to a module item. These declarations may appear in modules and blocks, usually at the top.

And,

• mod item

  A module item is a module, surrounded in braces, named, and prefixed with the keyword mod. A module item introduces a new, named module into the tree of modules making up a crate. Modules can nest arbitrarily.

Basically, when I go to layout my module, I believe I know how I want it layed out but I get confused about how these two things should be layered and what they do. I would think only one of the two would include code?

Answer 1

Consider you have a module my_mod with a pub function my_func. You can't use this function in your crate (or outside your crate) until you include your module using mod my_mod statement.

After you include your module, you can use your function like that:

mod my_mod;

...
my_mod::my_func(...)
...

You can't use my_mod::my_func statement if you don't include your module somewhere in your crate.

Sometimes it is better to import frequently used definitions:

mod my_mod;
use my_mod::my_func;

Now you if you want to use you function you can just write:

my_func(...);

You can also re-export definitions of sub-modules (or even other crates!) using pub use statement.

If you working with other crates imported through Cargo.toml (by listing them as dependencies), you may import definitions from these crates using only use statement.

Answer 2

The language documentation tries but misses a few important concepts implied by mod and I have had to do test to figure this out. To try an save others the time I offer the following conclusions...

1. The module system hierarchy forms a source tree where mod is restricted to referring to and thereby only being able to import immediate child modules. This limitation is not explicit in the documentation (or I missed it). That means sibling modules cannot import each other nor can they import parents, grandchildren, or cousin modules... The pattern does reflected the hierarchical containment of inline modules as well as the natural file system hierarchy of files being contained by only one directory (barring linked files). The key exception to this pattern and perhaps the source of confusion are root modules (main.rs, lib.rs, bin/other_root.rs). These modules mod's actually refer to sibling source files located in the crate root (src/) as well giving the false impression that mod can import siblings when it cannot. Crate root modules (main.rs, lib.rs, bin/other_root.rs) are treated as parent modules to all other modules in the src/ directory.
2. The modules included by crate roots (and also Cargo.toml) construct a source tree by selecting the initial modules they include. Those modules then include a selection of their children and so on. The resultant tree becomes the only source code available in the crate. Crate roots (lib.rs, main.rs, bin/other_crate_root.rs) may ultimate select different initial modules from the `/src' directory and thereby evolve a different tree of modules.
3. Finally, once a module does exist within the source tree of a crate it may be referred to by its path (depending on visibility constraints). In particular, use may now be used to abbreviate path to items.

Answer 3

mod keyword is like import statement. You bring the content from outside file.

 // another_file is the name of the file, another_file.rs
 mod another_file

Now you brought the content. use is used to create a path top-level so you could use a function or struct in multiple parts. Let's say you have to reach a struct deep inside the module:

use another_file::my_game::education::learning_rust::Person;

then inside main

fn main(){
    let person=Person::new()
    person.display_info();
    }

If I did not use use keyword, everwhere I needed Person struct I would write this:

let person=another_file::my_game::education::learning_rust::Person::new()

Also if you want to access standard library features, you use use

  use std::net;
  use std::io::prelude::*;