Update canonicalize docs
I was recently working with file-paths in Rust, and I felt let down by the `std::fs::canonicalize` docs, so I figured I should submit a PR with some suggestions.
I was looking for a method to turn a relative path into an absolute path. The `canonicalize` docs didn't mention the words "relative" or "absolute", but they did mention resolving symlinks (which is a kind of canonicalisation and does not imply converting to absolute), so I assumed that's all it did. To remedy this, I've added the word "absolute" to the description of both `std::fs::canonicalize` and `std::path::Path::canonicalize`.
After calling `canonicalize` on Windows, I ran into a bunch of other problems I would not have expected from the function's behaviour on Linux. Specifically, if you call `canonicalize` on a path:
- it's allowed to be much longer than it otherwise would
- `.join("a/slash/delimited/path")` gives you a broken path that Windows can't use, where the same operation would have worked perfectly without `canonicalize` (if the path were short enough)
- the resulting path may confuse other Windows programs if you pass it to them on the command-line, or write it to a config file that they read, etc.
...so I tried to summarize those behaviours too.
If I understand correctly, those behaviours are a side-effect of calling `GetFinalPathNameByHandle`, and the documentation says `canonicalize` might not call that function in future, so maybe those side-effects shouldn't be part of the function's documentation. However, I bet there's a lot of applications deliberately calling `canonicalize` just for the path-length-extension alone, so that particular side-effect is de-facto part of the `canonicalize` interface.
Rollup of 18 pull requests
Successful merges:
- #49423 (Extend tests for RFC1598 (GAT))
- #50010 (Give SliceIndex impls a test suite of girth befitting the implementation (and fix a UTF8 boundary check))
- #50447 (Fix update-references for tests within subdirectories.)
- #50514 (Pull in a wasm fix from LLVM upstream)
- #50524 (Make DepGraph::previous_work_products immutable)
- #50532 (Don't use Lock for heavily accessed CrateMetadata::cnum_map.)
- #50538 ( Make CrateNum allocation more thread-safe. )
- #50564 (Inline `Span` methods.)
- #50565 (Use SmallVec for DepNodeIndex within dep_graph.)
- #50569 (Allow for specifying a linker plugin for cross-language LTO)
- #50572 (Clarify in the docs that `mul_add` is not always faster.)
- #50574 (add fn `into_inner(self) -> (Idx, Idx)` to RangeInclusive (#49022))
- #50575 (std: Avoid `ptr::copy` if unnecessary in `vec::Drain`)
- #50588 (Move "See also" disambiguation links for primitive types to top)
- #50590 (Fix tuple struct field spans)
- #50591 (Restore RawVec::reserve* documentation)
- #50598 (Remove unnecessary mutable borrow and resizing in DepGraph::serialize)
- #50606 (Retry when downloading the Docker cache.)
Failed merges:
- #50161 (added missing implementation hint)
- #50558 (Remove all reference to DepGraph::work_products)
Map the stack guard page with max protection on NetBSD
On NetBSD the initial mmap() protection of a mapping can not be made
less restrictive with mprotect().
So when mapping a stack guard page, use the maximum protection
we ever want to use, then mprotect() it to the permission we
want it to have initially.
Fixes#50313
Add some explanations for #[must_use]
`#[must_use]` can be given a string argument which is shown whilst warning for things.
We should add a string argument to most of the user-exposed ones.
I added these for everything but the operators, mostly because I'm not sure what to write there or if we need anything there.
These are unstable, and were deprecated by #47510, since Rust 1.25. The
internal `sys` implementations are still kept to support the call in the
common `resolve_socket_addr`.
Forbid constructing empty identifiers from concat_idents
The empty identifier is a [reserved identifier](https://github.com/rust-lang/rust/blob/8a37c75a3a661385cc607d934c70e86a9eaf5fd7/src/libsyntax_pos/symbol.rs#L300-L305) in rust, apparently used for black magicks like representing the crate root or somesuch... and therefore, being able to construct it is Ungood. Presumably.
...even if the macro that lets you construct it is so useless that you can't actually do any damage with it. (and believe me, I tried)
Fixes#50403.
**Note:** I noticed that when you try to do something similar with `proc_macro::Term`, the compiler actually catches it and flags the identifier as reserved. Perhaps a better solution would be to somehow have that same check applied here.
While currently only NetBSD seems to be affected, all systems
implementing PAX MPROTECT in strict mode need this treatment,
and it does not hurt others.
Rollup of 7 pull requests
Successful merges:
- #50233 (Make `Vec::new` a `const fn`)
- #50312 (Add more links in panic docs)
- #50316 (Fix some broken links in docs.)
- #50325 (Add a few more tests for proc macro feature gating)
- #50327 (Display correct unused field suggestion for nested struct patterns)
- #50330 (check that #[used] is used only on statics)
- #50344 (Update Cargo to 2018-04-28 122fd5be5201913d42e219e132d6569493583bca)
Failed merges:
Add more links in panic docs
Fixes#48695 by adding a link to `AssertUnwindSafe`. Also added some other links in the module's docs to make things clearer.
Bury Error::description()
Second attempt of #49536https://github.com/rust-lang/rfcs/pull/2230
The exact wording of the default implementation is still up in the air, but I think it's a detail that can be amended later.
On NetBSD the initial mmap() protection of a mapping can not be made
less restrictive with mprotect().
So when mapping a stack guard page, use the maximum protection
we ever want to use, then mprotect() it to the permission we
want it to have initially.
… rather than the module’s.
Remove code definition of the Error trait from its doc-comment
It was out of date, and rustdoc already shows the same information.
Add a default impl for Error::description and document it as deprecated.
It is redundant with Display while being much less flexible for implementors.
This is only a "soft" deprecation: it is not worth the hassle of a warning to existing users.
Tweak Error trait docs to reflect actual requirements
Android abstract unix domain sockets AddressKind correction
The prior check causes abstract unix domain sockets to return AddressKind::Unnamed instead of AddressKind::Abstract on Android.
Other than the immediately proceeding comment "macOS seems to return a len of 16 and a zeroed sun_path for unnamed addresses" the check as-implemented does not seem to have alternative explanation. I couldn't find an alternative explanation while stepping though git blame. I suspect the AddressKind::Unnamed nonzero check should instead be if macos, length 16, and zeroed array. @sfackler could you comment on this, the code as-is is the same from your initial addition of abstract uds support.
Add doc links to `std::os` extension traits
Addresses a small subset of #29367.
This adds documentation links to the original type for various OS-specific extension traits, and uses a common sentence for introducing such traits (which now consistently ends in a period).
std: Child::kill() returns error if process has already exited
This patch makes it clear in std::process::Child::kill()'s API
documentation that an error is returned if the child process has
already cleanly exited. This is implied by the example, but not
called out explicitly.
Make signature of Path::strip_prefix accept non-references
I did this a while back but didn't submit a PR. Might as well see what happens.
Fixes#48390.
**Note: This has the potential to cause regressions in type inference.** However, in order for code to break, it would need to be relying on the signature to determine that a type is `&_`, while still being able to figure out what the `_` is. I'm having a hard time imagining such a scenario in real code.
Add inherent methods in libcore for [T], [u8], str, f32, and f64
# Background
Primitive types are defined by the language, they don’t have a type definition like `pub struct Foo { … }` in any crate. So they don’t “belong” to any crate as far as `impl` coherence is concerned, and on principle no crate would be able to define inherent methods for them, without a trait. Since we want these types to have inherent methods anyway, the standard library (with cooperation from the compiler) bends this rule with code like [`#[lang = "u8"] impl u8 { /*…*/ }`](https://github.com/rust-lang/rust/blob/1.25.0/src/libcore/num/mod.rs#L2244-L2245). The `#[lang]` attribute is permanently-unstable and never intended to be used outside of the standard library.
Each lang item can only be defined once. Before this PR there is one impl-coherence-rule-bending lang item per primitive type (plus one for `[u8]`, which overlaps with `[T]`). And so one `impl` block each. These blocks for `str`, `[T]` and `[u8]` are in liballoc rather than libcore because *some* of the methods (like `<[T]>::to_vec(&self) -> Vec<T> where T: Clone`) need a global memory allocator which we don’t want to make a requirement in libcore. Similarly, `impl f32` and `impl f64` are in libstd because some of the methods are based on FFI calls to C’s `libm` and we want, as much as possible, libcore not to require “runtime support”.
In libcore, the methods of `str` and `[T]` that don’t allocate are made available through two **unstable traits** `StrExt` and `SliceExt` (so the traits can’t be *named* by programs on the Stable release channel) that have **stable methods** and are re-exported in the libcore prelude (so that programs on Stable can *call* these methods anyway). Non-allocating `[u8]` methods are not available in libcore: https://github.com/rust-lang/rust/issues/45803. Some `f32` and `f64` methods are in an unstable `core::num::Float` trait with stable methods, but that one is **not in the libcore prelude**. (So as far as Stable programs are concerns it doesn’t exist, and I don’t know what the point was to mark these methods `#[stable]`.)
https://github.com/rust-lang/rust/issues/32110 is the tracking issue for these unstable traits.
# High-level proposal
Since the standard library is already bending the rules, why not bend them *a little more*? By defining a few additional lang items, the compiler can allow the standard library to have *two* `impl` blocks (in different crates) for some primitive types.
The `StrExt` and `SliceExt` traits still exist for now so that we can bootstrap from a previous-version compiler that doesn’t have these lang items yet, but they can be removed in next release cycle. (`Float` is used internally and needs to be public for libcore unit tests, but was already `#[doc(hidden)]`.) I don’t know if https://github.com/rust-lang/rust/issues/32110 should be closed by this PR, or only when the traits are entirely removed after we make a new bootstrap compiler.
# Float methods
Among the methods of the `core::num::Float` trait, three are based on LLVM intrinsics: `abs`, `signum`, and `powi`. PR https://github.com/rust-lang/rust/pull/27823 “Remove dependencies on libm functions from libcore” moved a bunch of `core::num::Float` methods back to libstd, but left these three behind. However they aren’t specifically discussed in the PR thread. The `compiler_builtins` crate defines `__powisf2` and `__powidf2` functions that look like implementations of `powi`, but I couldn’t find a connection with the `llvm.powi.f32` and `llvm.powi.f32` intrinsics by grepping through LLVM’s code.
In discussion starting at https://github.com/rust-lang/rust/issues/32110#issuecomment-370647922 Alex says that we do not want methods in libcore that require “runtime support”, but it’s not clear whether that applies to these `abs`, `signum`, or `powi`. In doubt, I’ve **removed** them for the trait and moved them to inherent methods in libstd for now. We can move them back later (or in this PR) if we decide that’s appropriate.
# Change details
For users on the Stable release channel:
* I believe this PR does not make any breaking change
* Some methods for `[u8]`, `f32`, and `f64` are newly available to `#![no_std]` users (fixes https://github.com/rust-lang/rust/issues/45803)
* There should be no visible change for `std` users in terms of what programs compile or what their behavior is. (Only in compiler error messages, possibly.)
For Nightly users, additionally:
* The unstable `StrExt` and `SliceExt` traits are gone
* Their methods are now inherent methods of `str` and `[T]` (so only code that explicitly named the traits should be affected, not "normal" method calls)
* The `abs`, `signum` and `powi` methods of the `Float` trait are gone
* The `Float` trait’s unstable feature name changed to `float_internals` with no associated tracking issue, to reflect it being a permanently unstable implementation detail rather than a public API on a path to stabilization.
* Its remaining methods are now inherent methods of `f32` and `f64`.
-----
CC @rust-lang/libs for the API changes, @rust-lang/compiler for the new lang items
Revert stabilization of never_type (!) et al
Fix#49691
I *think* this correctly adopts @nikomatsakis 's desired fix of:
* reverting stabilization of `!` and `TryFrom`, and
* returning to the previous fallback semantics (i.e. it is once again dependent on whether the crate has opted into `#[feature(never_type)]`,
* **without** attempting to put back in the previous future-proofing warnings regarding the change in fallback semantics.
(I'll be away from computers for a week starting now, so any updates to this PR should be either pushed into it, or someone else should adopt the task of polishing this fix and put up their own PR.)
Corey Farwell
