diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index 63eb70e..f52b5f9 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -34,23 +34,9 @@ "icon": "lucide-file", "title": "Modules and Use" } - }, - { - "id": "773e0725828dabb7", - "type": "leaf", - "state": { - "type": "markdown", - "state": { - "file": "Project Organization.md", - "mode": "source", - "source": false - }, - "icon": "lucide-file", - "title": "Project Organization" - } } ], - "currentTab": 2 + "currentTab": 1 } ], "direction": "vertical" @@ -192,18 +178,19 @@ "command-palette:Open command palette": false } }, - "active": "773e0725828dabb7", + "active": "b80f5219fa24358f", "lastOpenFiles": [ - "data_types.md", + "Packages.md", + "Crates.md", "Project Organization.md", - "does_not_compile.svg", + "crates.io.md", "Modules and Use.md", + "Paths.md", + "data_types.md", + "does_not_compile.svg", "Structures.md", "Primitives.md", - "Paths.md", - "Crates.md", "Untitled.canvas", - "Packages.md", "Enums.md", "Packages and Crates.md", "Good and Bad Code/Commenting Pratices", diff --git a/Modules and Use.md b/Modules and Use.md index 239f744..b34a99d 100644 --- a/Modules and Use.md +++ b/Modules and Use.md @@ -75,4 +75,148 @@ modules allow for the control of privacy, implementations needs to be declared a public modules and implementations can allow for different code to depend on it -this should be used to organize code like a file directory \ No newline at end of file +this should be used to organize code like a file directory + +## Use with Modules +This is a quick way to bring into scope a module then refer to the public items associated with module + +Use can be used with either the entire module or just one part of the module + +```rust +use crate::example_mod::sub_mod; +use crate::example_mod::sub_mod::example_funct; + +// --snip-- +// consumption +sub_mod::example_funct(); +example_funct(); +``` + +The use statement must be in the module scope if defined in the same file + +ex of proper use +```rust +mod another_mod { + use crate::example_mod::sub_mod::example_funct; + // --snip-- +} +// dont do this but you can +use crate::example_mod::sub_mod::example_funct; +mod another_mod { + use super::example_funct; + super::example_funct(); + // --snip-- +} +``` + +ex not allowed + +```rust +use crate::example_mod::sub_mod::example_funct; +mod another_mod { + // --snip-- +} +``` + +### Use the Idiomatic Path +``use crate::example_mod::sub_mod;`` this is the idiomatic path due to being able to call functions, structs, etc. inside the mod + +``use crate::example_mod::sub_mod::mod_fn;`` +this is not idiomatic due to specifying only one thing in the module + +this is great for letting others know it is not defined in the same module/crate as where it is being called this is only for functions + +for structs and enums it makes more sense to bring the whole object into scope then using the methods associated + +this is just convention in rust + +the exception to this convention is when bringing who items with the name name into scope because rust wont allow that and no one can read which call it is supposed to be +```rust +use std::fmt; +use std::io; + +fn function1() -> fmt::Result { + // --snip-- +} + +fn function2() -> io::Result<()> { + // --snip-- +} +``` + +Result makes no sense unless looking at input or slight differences + +Then use the parent mod to do so if this is the case + +### Providing New Names with the ``as`` Keyword +Here is the other solution to the similar names problem +```rust +use std::fmt::Result; +use std::io::Result as IoResult; + +fn function1() -> Result { + // --snip-- +} + +fn function2() -> IoResult<()> { + // --snip-- +} +``` + +as you can now see Result and IoResult may be called the same thing under the hood but now you can differentiate between the two + +this is also an accepted convention in rust + +### Re-exporting Names with ``pub use`` +the name that is brough into scope with use is private, but you can make it public to the whole module then you can add pub before use + +```rust +mod front_of_house { + pub mod hosting { + pub fn add_to_waitlist() {} + } +} + +pub use crate::front_of_house::hosting; + +pub fn eat_at_restaurant() { + hosting::add_to_waitlist(); +} +``` + +this would be like defining it as if it was defining it in the scope that is desired + +this also would have required front_of_house to also be marked public + +this is useful when the internal structure of your code is different from how programmers would call your code + +for example a customer would not think about frontend and backend they would think of add_to_waitlist and hosting not who's job it is + +Will be added onto in ch 14 + +### Nested Paths/Shortening Use +this is a technique to shorten the use vertical space that it can often take up + +```rust +use std::cmp::Ordering; +use std::io; +// this is the same as +use std::{cmp::Ordering, io}; +``` + +this specifies a common path between the two + +this can reduce the number of times that use shows up by A LOT + +## Glob Operator on Use +Use if you want to bring all sub children of a path into scope +```rust +use std::collections::*; +``` +This brings all public items defined in ``std::collections`` into the current scope + +This makes it harder to tell what names are used in scope and where a name in used in your program + +This is often used when testing to bring everything under test into the tests module + +This is also used as part of the prelude pattern diff --git a/Packages.md b/Packages.md index cb471ed..cd25cf1 100644 --- a/Packages.md +++ b/Packages.md @@ -8,4 +8,27 @@ packages can have as many binary crates as you want but only at most one library packages must have at least one crate -packages are defined by the toml file that comes with creating a new crate \ No newline at end of file +packages are defined by the toml file that comes with creating a new crate + +# External Packages + +These crates are normally found on [crates.io](https://crates.io/) +in the guessing game the external crate was first defined in the cargo.toml as +```toml +rand = "0.8.5" +``` + +it was then brough into scope by +```rust +use rand::Rng; +// and then used +rand::thread_rng().gen_range(0..=100); +``` + +pulling other modules is often the same process + +the std library is an external package but it doesn't need to be specified in the toml file + +but it does need to be brought into scope with the ``use`` keyword + +the std::other_part is an absolute path starting with std for the standard library crate \ No newline at end of file