mirror of
https://github.com/darkicewolf50/RustBrock.git
synced 2025-06-15 04:54:17 -06:00
78 lines
3.3 KiB
Markdown
78 lines
3.3 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/)
|
|
|
|
## Starting Relative Paths with super
|
|
can contract relative paths starting at the parent rather than the root of the crate
|
|
|
|
This is done by using the ``super`` keyword at the start of the path it is equivalent to the ``..`` syntax
|
|
useful for accessing items that we know are in the parent module which can make rearranging the module tree easier when the module is closely related to the parent but may be moved in the future
|
|
|
|
```rust
|
|
super::deliver_order();
|
|
```
|
|
deliver order now can be located else where in the parent module and not forced to be in the child module
|