mirror of
https://github.com/darkicewolf50/RustBrock.git
synced 2025-06-15 13:04:18 -06:00
67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
# Paths
|
|
|
|
## Paths for Referring to an Item in the Module Tree
|
|
to show the rust compiler where to find an item in a module tree we use a path similar to navigating a filesystem, where the function is located
|
|
|
|
A path can be two forms:
|
|
- *Absolute path* - the full path starting from a crate root to the code of an external crate, the absolute path begins with the crate name and for code form the current crate it starts with the literal *crate*
|
|
- *Relative path* - starts from the current module and uses ``self``, ``super``, or an identifier in the current module
|
|
Both types of paths are followed by one or more identifiers separated by ``::``
|
|
|
|
module tree for example
|
|
```
|
|
crate
|
|
└── front_of_house
|
|
├── hosting
|
|
│ ├── add_to_waitlist
|
|
│ └── seat_at_table
|
|
└── serving
|
|
├── take_order
|
|
├── serve_order
|
|
└── take_payment
|
|
```
|
|
|
|
```rust
|
|
// Absolute path
|
|
crate::front_of_house::hosting::add_to_waitlist();
|
|
|
|
// Relative path
|
|
front_of_house::hosting::add_to_waitlist();
|
|
```
|
|
|
|
these are both calls to different parts of a different module from the parent crate named ``crate``
|
|
this is equivalent to ``/front_of_house/hosting/add_to_waitlist`` in another language where the first ``/`` is the crate root or the ``./``
|
|
|
|
choose the pathing based off your requirements/future organization of code
|
|
preference is to specify absolute paths because more likely to move code definitions and item calls independently of each other
|
|
|
|
rust will be able to tell the difference between a private function and a wrong path error
|
|
|
|
any function, method, struct, enum, module and constants are private by default
|
|
|
|
child modules can use parent modules but parent modules cannot use child modules
|
|
|
|
child modules wrap their implementation to those above but not to itself or below
|
|
|
|
you use pub keyword to expose to the parent module
|
|
this is done so that you know what breaks your code
|
|
|
|
this is valid and allows for the outermost crate to access the function add_to_watlist through the root defined front_of_house module
|
|
```rust
|
|
mod front_of_house {
|
|
pub mod hosting {
|
|
pub fn add_to_waitlist() {}
|
|
}
|
|
}
|
|
```
|
|
|
|
it is called by ``crate::front_of_house::hosting::add_to_waitlist();``
|
|
from the sister module/function
|
|
if it was up another level then front_of_house would need a pub
|
|
|
|
can be called by the relative path ``front_of_house::hosting::add_to_waitlist();``
|
|
|
|
the public API that is determined by the developer is the contract with the users through other crates.
|
|
There are many considerations to your public api to make it easier for people to depend on your crate
|
|
These details and considerations are more concretely outlined in the [The Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
|