Use matches macro in libcore and libstd
This PR replaces matches like
```rust
match var {
value => true,
_ => false,
}
```
with use of `matches!` macro.
r? @Centril
`description` has been documented as soft-deprecated since 1.27.0 (17
months ago). There is no longer any reason to call it or implement it.
This commit:
- adds #[rustc_deprecated(since = "1.41.0")] to Error::description;
- moves description (and cause, which is also deprecated) below the
source and backtrace methods in the Error trait;
- reduces documentation of description and cause to take up much less
vertical real estate in rustdocs, while preserving the example that
shows how to render errors without needing to call description;
- removes the description function of all *currently unstable* Error
impls in the standard library;
- marks #[allow(deprecated)] the description function of all *stable*
Error impls in the standard library;
- replaces miscellaneous uses of description in example code and the
compiler.
This commit applies rustfmt with rust-lang/rust's default settings to
files in src/libstd *that are not involved in any currently open PR* to
minimize merge conflicts. THe list of files involved in open PRs was
determined by querying GitHub's GraphQL API with this script:
https://gist.github.com/dtolnay/aa9c34993dc051a4f344d1b10e4487e8
With the list of files from the script in outstanding_files, the
relevant commands were:
$ find src/libstd -name '*.rs' \
| xargs rustfmt --edition=2018 --unstable-features --skip-children
$ rg libstd outstanding_files | xargs git checkout --
Repeating this process several months apart should get us coverage of
most of the rest of libstd.
To confirm no funny business:
$ git checkout $THIS_COMMIT^
$ git show --pretty= --name-only $THIS_COMMIT \
| xargs rustfmt --edition=2018 --unstable-features --skip-children
$ git diff $THIS_COMMIT # there should be no difference
Correct deprecated `is_global` IPv6 documentation
This method does currently not return false for the `site_local` unicast address space. The documentation of the `is_unicast_global` method on lines 1352 - 1382 suggests that this is intentional as the site-local prefix must no longer be supported in new implementations, thus the documentation can safely be updated to reflect that information.
If not so, either the `is_unicast_global` method should be updated to exclude the unicast site-local address space, or the `is_global` method itself.
This method does currently not return false for the `site_local` unicast address space. The documentation of the `is_unicast_global` method on lines 1352 - 1382 suggests that this is intentional as the site-local prefix must no longer be supported in new implementations, thus the documentation can safely be updated to reflect that information.
If not so, either the `is_unicast_global` method should be updated to exclude the unicast site-local address space, or the `is_global` method itself.
std::net: Ipv4Addr and Ipv6Addr improvements
Picking this up again from my previous PR: https://github.com/rust-lang/rust/pull/56050
Related to: https://github.com/rust-lang/rust/issues/27709
Fixes: https://github.com/rust-lang/rust/issues/57558
- add `add Ipv4Addr::is_reserved()`
- [X] implementation
- [X] tests
- add `Ipv6Addr::is_unicast_link_local_strict()` and update `Ipv6Addr::is_unicast_link_local()` documentation
- [X] implementation
- [X] test
- add `Ipv4Addr::is_benchmarking()`
- [X] implementation
- [X] test
- add `Ipv4Addr::is_ietf_protocol_assignment()`
- [X] implementation
- [X] test
- add `Ipv4Addr::is_shared()`
- [X] implementation
- [x] test
- fix `Ipv4Addr:is_global()`
- [X] implementation
- [x] test
- [X] refactor the tests for IP properties. This makes the tests more verbose, but using macros have two advantages:
- it will now be easier to add tests for all the new methods
- we get clear error messages when a test is failing. For instance:
```
---- net::ip::tests::ip_properties stdout ----
thread '<unnamed>' panicked at 'assertion failed: !ip!("fec0::").is_global()', src/libstd/net/ip.rs:2036:9
```
Whereas previously it was something like
```
thread '<unnamed>' panicked at 'assertion failed: `(left == right)`
left: `true`,
right: `false`', libstd/net/ip.rs:1948:13
```
-----------------------
# Ongoing discussions:
## Should `Ipv4Addr::is_global()` return `true` or `false` for reserved addresses?
Reserved addresses are addresses that are matched by `Ipv4Addr::is_reserved()`.
@the8472 [pointed out](https://github.com/rust-lang/rust/pull/60145#issuecomment-485458319) that [RFC 4291](https://tools.ietf.org/html/rfc4291#section-2.4) says IPv6 reserved addresses should be considered global:
```
Future specifications may redefine one or more sub-ranges of the
Global Unicast space for other purposes, but unless and until that
happens, implementations must treat all addresses that do not start
with any of the above-listed prefixes as Global Unicast addresses.
```
We could extrapolate that this should also be the case for IPv4. However, it seems that [IANA considers them non global](https://www.iana.org/assignments/ipv4-address-space/ipv4-address-space.xhtml) (see [my comment](https://github.com/rust-lang/rust/pull/60145#issuecomment-485713270))
### Final decision
There seems to be a consensus that reserved addresses have a different meaning for IPv4 and IPv6 ([comment1](https://github.com/rust-lang/rust/pull/60145#issuecomment-485963789) [comment2](https://github.com/rust-lang/rust/pull/60145#issuecomment-485944582), so we can consider that RFC4291 does not apply to IPv4, and that reserved IPv4 addresses are _not_ global.
## Should `Ipv6Addr::is_unicast_site_local()` exist?
@pusateri [noted](https://github.com/rust-lang/rust/pull/60145#issuecomment-485507515) that site-local addresses have been deprecated for a while by [RFC 3879](https://tools.ietf.org/html/rfc3879) and new implementations _must not_ support them. However, since this method is stable, removing does not seem possible. This kind of situation is covered by the RFC which stated that existing implementation _may_ continue supporting site-local addresses.
### Final decision
Let's keep this method. It is stable already, and the RFC explicitly states that existing implementation may remain.
---------
Note: I'll be AFK from April 27th to May 11th. Anyone should feel free to pick this up if the PR hasn't been merged by then. Sorry for dragging that for so long already.
Fix intra-doc link resolution failure on re-exporting libstd
Currently, re-exporting libstd items as below will [occur a lot of failures](https://gist.github.com/taiki-e/e33e0e8631ef47f65a74a3b69f456366).
```rust
pub use std::*;
```
Until the underlying issue (#56922) fixed, we can fix that so they don't propagate to downstream crates.
Related: https://github.com/rust-lang/rust/pull/56941 (That PR fixed failures that occur when re-exporting from libcore to libstd.)
r? @QuietMisdreavus
This renames `std::io::IoVec` to `std::io::IoSlice` and
`std::io::IoVecMut` to `std::io::IoSliceMut`, and stabilizes
`std::io::IoSlice`, `std::io::IoSliceMut`,
`std::io::Read::read_vectored`, and `std::io::Write::write_vectored`.
Closes#58452
See @the8472 comment's on Github:
https://github.com/rust-lang/rust/pull/60145#issuecomment-485424229
> I don't think is_reserved including ranges marked for future use is
> a good idea since those future uses may be realized at at some point
> and then old software with is_reserved filters may have false
> positives. This is not a hypothetical concern, such issues have been
> encountered before when IANA assigned previously reserved /8 address
> blocks.
As per @therealbstern's comment[0]:
The implementation of Ipv4::is_global is not complete, according to the
IANA IPv4 Special-Purpose Address Registry.
- It compares the address to 0.0.0.0, but anything in 0.0.0.0/8
should not be considered global.
- 0/8 is not global and is currently forbidden because
some systems used to treat it as the local network.
- The implementation of Ipv4::is_unspecified is correct.
0.0.0.0 is the unspecified address.
- It does not examine 100.64.0.0/10, which is "Shared Address
Space" and not global.
- Ditto 192.0.0.0/24 (IETF Protocol Assignments), except for
192.0.0.9/32 and 192.0.0.10/32, which are carved out as
globally reachable.
- 198.18.0.0/15 is for "Benchmarking" and should not be globally
reachable.
- 240.0.0.0/4 is reserved and not currently reachable
RFC 4291 is a little unclear about what is a unicast link local address.
According to section 2.4, the entire fe80::/10 range is reserved for
these addresses, but section 2.5.3 defines a stricter format for such
addresses.
After a discussion[0] is has been decided to add a different method for
each definition, so this commit:
- renames is_unicast_link_local() into is_unicast_link_local_strict()
- relaxed the check in is_unicast_link_local()
[0]: https://github.com/rust-lang/rust/issues/27709#issuecomment-400370706
