Skip to content

Commit

Permalink
Drop "uniform path" terminology.
Browse files Browse the repository at this point in the history
  • Loading branch information
ehuss committed Jan 31, 2019
1 parent a2576a1 commit d1d7b8c
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 26 deletions.
3 changes: 1 addition & 2 deletions src/rust-2018/edition-changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ the 2018 edition compared to the 2015 edition.
- [Non-lexical lifetimes] (future inclusion planned for 2015 edition)
- [At most once] `?` macro repetition operator.
- [Path changes]:
- [Uniform paths] in `use` declarations.
- Paths in `use` declarations work the same as other paths.
- Paths staring with `::` must be followed with an external crate.
- Paths in `pub(in path)` visibility modifiers must start with `crate`,
`self`, or `super`.
Expand Down Expand Up @@ -38,5 +38,4 @@ the 2018 edition compared to the 2015 edition.
[reserved keywords]: https://doc.rust-lang.org/reference/keywords.html#reserved-keywords
[strict keyword]: https://doc.rust-lang.org/reference/keywords.html#strict-keywords
[tyvar_behind_raw_pointer]: https://github.com/rust-lang/rust/issues/46906
[uniform paths]: rust-2018/module-system/path-clarity.html#uniform-paths
[weak keyword]: https://doc.rust-lang.org/reference/keywords.html#weak-keywords
40 changes: 16 additions & 24 deletions src/rust-2018/module-system/path-clarity.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Here's a brief summary:
* Paths starting with `::` must reference an external crate.
* A `foo.rs` and `foo/` subdirectory may coexist; `mod.rs` is no longer needed
when placing submodules in a subdirectory.
* `use` declarations take [uniform paths](#uniform-paths).
* Paths in `use` declarations work the same as other paths.

These may seem like arbitrary new rules when put this way, but the mental
model is now significantly simplified overall. Read on for more details!
Expand Down Expand Up @@ -140,9 +140,6 @@ mod submodule {
// but in a submodule it requires a leading :: if not imported with `use`
let x = ::chrono::Utc::now();
}
// unlike expressions, `use` paths were allowed to reference crates directly
use chrono::Local;
}
```

Expand All @@ -162,9 +159,6 @@ mod submodule {
// crates may be referenced directly, even in submodules
let x = chrono::Utc::now();
}
// `use` paths have the same path style
use chrono::Local;
}
```

Expand Down Expand Up @@ -201,23 +195,22 @@ and the submodule is still `foo/bar.rs`. This eliminates the special
name, and if you have a bunch of files open in your editor, you can clearly
see their names, instead of having a bunch of tabs named `mod.rs`.

# Uniform paths
### `use` paths

![Minimum Rust version: 1.32](https://img.shields.io/badge/Minimum%20Rust%20Version-1.32-brightgreen.svg)

The uniform paths variant of Rust 2018 simplifies and unifies path handling
compared to Rust 2015. In Rust 2015, paths work differently in `use`
declarations than they do elsewhere. In particular, paths in `use`
declarations would always start from the crate root, while paths in other code
implicitly started from the current scope. Those differences didn't have any
effect in the top-level module, which meant that everything would seem
straightforward until working on a project large enough to have submodules.
Rust 2018 simplifies and unifies path handling compared to Rust 2015. In Rust
2015, paths work differently in `use` declarations than they do elsewhere. In
particular, paths in `use` declarations would always start from the crate
root, while paths in other code implicitly started from the current scope.
Those differences didn't have any effect in the top-level module, which meant
that everything would seem straightforward until working on a project large
enough to have submodules.

In the uniform paths variant of Rust 2018, paths in `use` declarations and in
other code almost always work the same way, both in the top-level module and
in any submodule. You can use a relative path from the current scope, a path
starting from an external crate name, or a path starting with `crate`,
`super`, or `self`.
In Rust 2018, paths in `use` declarations and in other code work the same way,
both in the top-level module and in any submodule. You can use a relative path
from the current scope, a path starting from an external crate name, or a path
starting with `crate`, `super`, or `self`.

Code that looked like this:

Expand Down Expand Up @@ -255,7 +248,7 @@ will look exactly the same in Rust 2018, except that you can delete the `extern
crate` line:

```rust,ignore
// Rust 2018 (uniform paths variant)
// Rust 2018
use futures::Future;
Expand All @@ -282,11 +275,10 @@ fn func() {
}
```

With uniform paths, however, the same code will also work completely unmodified in
a submodule:
The same code will also work completely unmodified in a submodule:

```rust,ignore
// Rust 2018 (uniform paths variant)
// Rust 2018
mod submodule {
use futures::Future;
Expand Down

0 comments on commit d1d7b8c

Please sign in to comment.