Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the Preludes chapter for the 2021 edition changes to the standard library prelude #1136

Merged
merged 2 commits into from
Jan 24, 2022
Merged

Update the Preludes chapter for the 2021 edition changes to the standard library prelude #1136

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dfc94ed
Update for 2021 edition standard library prelude changes
mattheww Jan 15, 2022
0181f23
2021 edition standard library prelude changes: address review comments
mattheww Jan 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 25 additions & 9 deletions src/names/preludes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,21 @@ There are several different preludes:

## Standard library prelude

The standard library prelude includes names from the [`std::prelude::v1`]
module. If the [`no_std` attribute] is used, then it instead uses the names
from the [`core::prelude::v1`] module.
Each crate has a standard library prelude, which consists of the names from a single standard library module.
The module used depends on the crate's edition, and on whether the [`no_std` attribute] is applied to the crate:

Edition | `no_std` not applied | `no_std` applied
--------| --------------------------- | ----------------------------
2015 | [`std::prelude::rust_2015`] | [`core::prelude::rust_2015`]
2018 | [`std::prelude::rust_2018`] | [`core::prelude::rust_2018`]
2021 | [`std::prelude::rust_2021`] | [`core::prelude::rust_2021`]


> **Note**:
>
> [`std::prelude::rust_2015`] and [`std::prelude::rust_2018`] have the same contents as [`std::prelude::v1`].
>
> [`core::prelude::rust_2015`] and [`core::prelude::rust_2018`] have the same contents as [`core::prelude::v1`].

## Extern prelude

Expand Down Expand Up @@ -63,15 +75,13 @@ By default, the standard library is automatically included in the crate root
module. The [`std`] crate is added to the root, along with an implicit
[`macro_use` attribute] pulling in all macros exported from `std` into the
[`macro_use` prelude]. Both [`core`] and [`std`] are added to the [extern
prelude]. The [standard library prelude] includes everything from the
[`std::prelude::v1`] module.
prelude].

The *`no_std` [attribute]* may be applied at the crate level to prevent the
[`std`] crate from being automatically added into scope. It does three things:

* Prevents `std` from being added to the [extern prelude](#extern-prelude).
* Uses [`core::prelude::v1`] in the [standard library prelude] instead of
[`std::prelude::v1`].
* Affects which module is used to make up the [standard library prelude] (as described above).
* Injects the [`core`] crate into the crate root instead of [`std`], and pulls
in all macros exported from `core` in the [`macro_use` prelude].

Expand Down Expand Up @@ -129,14 +139,20 @@ This attribute does not affect the [language prelude].

[`alloc`]: ../../alloc/index.html
[`Box`]: ../../std/boxed/struct.Box.html
[`core::prelude::v1`]: ../../core/prelude/index.html
[`core::prelude::v1`]: ../../core/prelude/v1/index.html
[`core::prelude::rust_2015`]: ../../core/prelude/rust_2015/index.html
[`core::prelude::rust_2018`]: ../../core/prelude/rust_2018/index.html
[`core::prelude::rust_2021`]: ../../core/prelude/rust_2021/index.html
[`core`]: ../../core/index.html
[`extern crate`]: ../items/extern-crates.md
[`macro_use` attribute]: ../macros-by-example.md#the-macro_use-attribute
[`macro_use` prelude]: #macro_use-prelude
[`no_std` attribute]: #the-no_std-attribute
[`no_std` attribute]: #the-no_std-attribute
[`std::prelude::v1`]: ../../std/prelude/index.html
[`std::prelude::v1`]: ../../std/prelude/v1/index.html
[`std::prelude::rust_2015`]: ../../std/prelude/rust_2015/index.html
[`std::prelude::rust_2018`]: ../../std/prelude/rust_2018/index.html
[`std::prelude::rust_2021`]: ../../std/prelude/rust_2021/index.html
[`std`]: ../../std/index.html
[`test`]: ../../test/index.html
[attribute]: ../attributes.md
Expand Down