Rewrite docs for `std::ptr`
This PR attempts to resolve#29371.
This is a fairly major rewrite of the `std::ptr` docs, and deserves a fair bit of scrutiny. It adds links to the GNU libc docs for various instrinsics, adds internal links to types and functions referenced in the docs, adds new, more complex examples for many functions, and introduces a common template for discussing unsafety of functions in `std::ptr`.
All functions in `std::ptr` (with the exception of `ptr::eq`) are unsafe because they either read from or write to a raw pointer. The "Safety" section now informs that the function is unsafe because it dereferences a raw pointer and requires that any pointer to be read by the function points to "a valid vaue of type `T`".
Additionally, each function imposes some subset of the following conditions on its arguments.
* The pointer points to valid memory.
* The pointer points to initialized memory.
* The pointer is properly aligned.
These requirements are discussed in the "Undefined Behavior" section along with the consequences of using functions that perform bitwise copies without requiring `T: Copy`. I don't love my new descriptions of the consequences of making such copies. Perhaps the old ones were good enough?
Some issues which still need to be addressed before this is merged:
- [ ] The new docs assert that `drop_in_place` is equivalent to calling `read` and discarding the value. Is this correct?
- [ ] Do `write_bytes` and `swap_nonoverlapping` require properly aligned pointers?
- [ ] The new example for `drop_in_place` is a lackluster.
- [ ] Should these docs rigorously define what `valid` memory is? Or should is that the job of the reference? Should we link to the reference?
- [ ] Is it correct to require that pointers that will be read from refer to "valid values of type `T`"?
- [x] I can't imagine ever using `{read,write}_volatile` with non-`Copy` types. Should I just link to {read,write} and say that the same issues with non-`Copy` types apply?
- [x] `write_volatile` doesn't link back to `read_volatile`.
- [ ] Update docs for the unstable [`swap_nonoverlapping`](https://github.com/rust-lang/rust/issues/42818)
- [ ] Update docs for the unstable [unsafe pointer methods RFC](https://github.com/rust-lang/rfcs/pull/1966)
Looking forward to your feedback.
r? @steveklabnik
Give SliceIndex impls a test suite of girth befitting the implementation (and fix a UTF8 boundary check)
So one day I was writing something in my codebase that basically amounted to `impl SliceIndex for (Bound<usize>, Bound<usize>)`, and I said to myself:
*Boy, gee, golly! I never realized bounds checking was so tricky!*
At some point when I had around 60 lines of tests for it, I decided to go see how the standard library does it to see if I missed any edge cases. ...That's when I discovered that libcore only had about 40 lines of tests for slicing altogether, and none of them even used `..=`.
---
This PR includes:
* **Literally the first appearance of the word `get_unchecked_mut` in any directory named `test` or `tests`.**
* Likewise the first appearance of `get_mut` used with _any type of range argument_ in these directories.
* Tests for the panics on overflow with `..=`.
* I wanted to test on `[(); usize::MAX]` as well but that takes linear time in debug mode </3
* A horrible and ugly test-generating macro for the `should_panic` tests that increases the DRYness by a single order of magnitude (which IMO wasn't enough, but I didn't want to go any further and risk making the tests inaccessible to next guy).
* Same stuff for str!
* Actually, the existing `str` tests were pretty good. I just helped filled in the holes.
* [A fix for the bug it caught](https://github.com/rust-lang/rust/issues/50002). (only one ~~sadly~~)
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.
Add more logarithm constants
Right now, we have `ln(2)` and `ln(10)`, but only `log2(e)` and `log10(e)`. This also adds `log2(10)` and `log10(2)` for consistency.
Prior to this, Duration simply derived Debug. Since Duration doesn't
implement `Display`, the only way to inspect its value is to use
`Debug`. Unfortunately, the derived `Debug` impl is far from optimal
for humans. In many cases, Durations are used for some quick'n'dirty
benchmarking (or in general: measuring the time of some code). Correctly
understanding the output of Duration's Debug impl is not easy (e.g.
is "{ secs: 0, nanos: 968360102 }" or "{ secs: 0, nanos 98507324 }"
shorter?).
This commit replaces the derived impl with a manual one. It prints
the duration as seconds (i.e. "3.1803s") if the duration is longer than
a second, otherwise it prints it in either ms, µs or ns (depending on
the duration's length). This already helps readability a lot and it
never omits information that is stored.
This `Debug` impl does *not* respect the following formatting parameters:
- fill/align/padding: difficult to implement, probably not worth it
- alternate # flag: not clear what this should do
All other tests of libcore reside in the tests/ directory,
too. Apparently the tests of `time.rs` weren't run before, at
least not by `x.py test src/libcore`.
nano-optimization for memchr::repeat_byte
This replaces the multiple shifts & bitwise or with a single multiplication
In my benchmarks this performs equally well or better, especially on 64bit systems (it shaves a stable nanosecond on my skylake). This may go against conventional wisdom, but the shifts and bitwise ors cannot be pipelined because of hard data dependencies.
While it may or may not be worthwile from an optimization standpoint, it also reduces code size, so there's basically no downside.
Forbid constructing empty identifiers from concat_idents
The empty identifier is a [reserved identifier](8a37c75a3a/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.
Fix a warning in libcore on 16bit targets.
This code is assuming that usize >= 32bits, but it is not the case on
16bit targets. It is producing a warning that can fail the compilation
on MSP430 if deny(warnings) is enabled.
It is very unlikely that someone would actually use this code on
a microcontroller, but since unicode was merged into libcore we
have to compile it on 16bit targets.
I've tried to make sure that the code stays the same on x86,
here is an assembly comparison: https://godbolt.org/g/wFw7dZ
r? @SimonSapin
This code is assuming that usize >= 32bits, but it is not the case on
16bit targets. It is producing a warning that will fail the compilation
on MSP430 if deny(warnings) is enabled.
It is very unlikely that someone would actually use this code on
a microcontroller, but since unicode was merged into libcore we
have compile it on 16bit targets.
Make `Vec::new` a `const fn`
`RawVec::empty/_in` are a hack. They're there because `if size_of::<T> == 0 { !0 } else { 0 }` is not allowed in `const` yet. However, because `RawVec` is unstable, the `empty/empty_in` constructors can be removed when #49146 is done...
