Due to #20400 the corresponding TrustedLen impls need a helper trait
instead of directly adding `Item = &[T;N]` bounds.
Since TrustedLen is a public trait this in turn means
the helper trait needs to be public. Since it's just a workaround
for a compiler deficit it's marked hidden, unstable and unsafe.
Correct invariant documentation for `steps_between`
Given that the previous example involves stepping forward from A to B, the equivalent example on this line would make most sense as stepping backward from B to A.
I should probably add a caveat here that I’m fairly new to Rust, and this is my first contribution to this repo, so it’s very possible that I’ve misunderstood how this is supposed to work (either on a technical level or a social one). If this is the case, please do let me know.
This only works if arrays are passed directly instead of array iterators
because we need to be sure that they have not been advanced before
Flatten does its size calculation.
Make the specialized Fuse still deal with None
Fixes#85863 by removing the assumption that we'll never see a cleared iterator in the `I: FusedIterator` specialization. Now all `Fuse` methods check for the possibility that `self.iter` is `None`, and the specialization only avoids _setting_ that to `None` in `&mut self` methods.
Given that the previous example involves stepping forward from A to B,
the equivalent example on this line would make most sense as stepping
backward from B to A.
expand: Support helper attributes for built-in derive macros
This is needed for https://github.com/rust-lang/rust/pull/86735 (derive macro `Default` should have a helper attribute `default`).
With this PR we can specify helper attributes for built-in derives using syntax `#[rustc_builtin_macro(MacroName, attributes(attr1, attr2, ...))]` which mirrors equivalent syntax for proc macros `#[proc_macro_derive(MacroName, attributes(attr1, attr2, ...))]`.
Otherwise expansion infra was already ready for this.
The attribute parsing code is shared between proc macro derives and built-in macros (`fn parse_macro_name_and_helper_attrs`).
create method overview docs for core::option and core::result
The `Option` and `Result` types have large lists of methods. They each could use an overview page of methods grouped by category. These proposed overviews include "truth tables" for the underappreciated boolean operators/combinators of these types. The methods are already somewhat categorized in the source, but some logical groupings are broken up by the necessities of putting related methods in different `impl` blocks, for example.
This is based on #86209, but those are small changes and unlikely to conflict.
Split MaybeUninit::write into new feature gate and stabilize it
This splits off the `MaybeUninit::write` function from the `maybe_uninit_extra` feature gate into a new `maybe_uninit_write` feature gate and stabilizes it.
Earlier work to improve the documentation of the write function: #86220
Tracking issue: #63567
This will not affect ABI since the other variant of the enum is bigger.
It may break some code, but that would be very strange: usually people
don't continue after the first `Done` (or `None` for a normal iterator).
- Add `:Sized` assertion in interpreter impl
- Use `Scalar::from_bool` instead of `ScalarInt: From<bool>`
- Remove unneeded comparison in intrinsic typeck
- Make this UB to call with undef, not just return undef in that case
special case for integer log10
Now that #80918 has been merged, this PR provides a faster version of `log10`.
The PR also adds some tests for values close to all powers of 10.
Use diagnostic items instead of lang items for rfc2229 migrations
This PR removes the `Send`, `UnwindSafe` and `RefUnwindSafe` lang items introduced in https://github.com/rust-lang/rust/pull/84730, and uses diagnostic items instead to check for `Send`, `UnwindSafe` and `RefUnwindSafe` traits for RFC2229 migrations.
r? ```@nikomatsakis```
Revert "Add "every" as a doc alias for "all"."
This reverts commit 35450365ac (#81697) for "every" and closes#86554 in kind for "some".
The new [doc alias policy](https://std-dev-guide.rust-lang.org/documentation/doc-alias-policy.html) is that we don't want language-specific aliases like these JavaScript names, and we especially don't want to conflict with real names. While "every" is okay in the latter regard, its natural pair "some" makes a doc-search collision with `Option::Some`.
r? ```@m-ou-se```
Rename some Rust 2021 lints to better names
Based on conversation in https://github.com/rust-lang/rust/issues/85894.
Rename a bunch of Rust 2021 related lints:
Lints that are officially renamed because they are already in beta or stable:
* `disjoint_capture_migration` => `rust_2021_incompatible_closure_captures`
* `or_patterns_back_compat` => `rust_2021_incompatible_or_patterns`
* `non_fmt_panic` => `non_fmt_panics`
Lints that are renamed but don't require any back -compat work since they aren't yet in stable:
* `future_prelude_collision` => `rust_2021_prelude_collisions`
* `reserved_prefix` => `rust_2021_token_prefixes`
Lints that have been discussed but that I did not rename:
* ~`non_fmt_panic` and `bare_trait_object`: is making this plural worth the headache we might cause users?~
* `array_into_iter`: I'm unsure of a good name and whether bothering users with a name change is worth it.
r? `@nikomatsakis`
Add Integer::log variants
_This is another attempt at landing https://github.com/rust-lang/rust/pull/70835, which was approved by the libs team but failed on Android tests through Bors. The text copied here is from the original issue. The only change made so far is the addition of non-`checked_` variants of the log methods._
_Tracking issue: #70887_
---
This implements `{log,log2,log10}` methods for all integer types. The implementation was provided by `@substack` for use in the stdlib.
_Note: I'm not big on math, so this PR is a best effort written with limited knowledge. It's likely I'll be getting things wrong, but happy to learn and correct. Please bare with me._
## Motivation
Calculating the logarithm of a number is a generally useful operation. Currently the stdlib only provides implementations for floats, which means that if we want to calculate the logarithm for an integer we have to cast it to a float and then back to an int.
> would be nice if there was an integer log2 instead of having to either use the f32 version or leading_zeros() which i have to verify the results of every time to be sure
_— [`@substack,` 2020-03-08](https://twitter.com/substack/status/1236445105197727744)_
At higher numbers converting from an integer to a float we also risk overflows. This means that Rust currently only provides log operations for a limited set of integers.
The process of doing log operations by converting between floats and integers is also prone to rounding errors. In the following example we're trying to calculate `base10` for an integer. We might try and calculate the `base2` for the values, and attempt [a base swap](https://www.rapidtables.com/math/algebra/Logarithm.html#log-rules) to arrive at `base10`. However because we're performing intermediate rounding we arrive at the wrong result:
```rust
// log10(900) = ~2.95 = 2
dbg!(900f32.log10() as u64);
// log base change rule: logb(x) = logc(x) / logc(b)
// log2(900) / log2(10) = 9/3 = 3
dbg!((900f32.log2() as u64) / (10f32.log2() as u64));
```
_[playground](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=6bd6c68b3539e400f9ca4fdc6fc2eed0)_
This is somewhat nuanced as a lot of the time it'll work well, but in real world code this could lead to some hard to track bugs. By providing correct log implementations directly on integers we can help prevent errors around this.
## Implementation notes
I checked whether LLVM intrinsics existed before implementing this, and none exist yet. ~~Also I couldn't really find a better way to write the `ilog` function. One option would be to make it a private method on the number, but I didn't see any precedent for that. I also didn't know where to best place the tests, so I added them to the bottom of the file. Even though they might seem like quite a lot they take no time to execute.~~
## References
- [Log rules](https://www.rapidtables.com/math/algebra/Logarithm.html#log-rules)
- [Rounding error playground](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=6bd6c68b3539e400f9ca4fdc6fc2eed0)
- [substack's tweet asking about integer log2 in the stdlib](https://twitter.com/substack/status/1236445105197727744)
- [Integer Logarithm, A. Jaffer 2008](https://people.csail.mit.edu/jaffer/III/ilog.pdf)
Remove some doc aliases
As per the new doc alias policy in https://github.com/rust-lang/std-dev-guide/pull/25, this removes some controversial doc aliases:
- `malloc`, `alloc`, `realloc`, etc.
- `length` (alias for `len`)
- `delete` (alias for `remove` in collections and also file/directory deletion)
r? `@joshtriplett`
aborts: Clarify documentation and comments
In the docs for intrinsics::abort():
* Strengthen the recommendation by to use process::abort instead.
* Document the fact that it sometimes (ab)uses an LLVM debug trap and what the likely consequences are.
* State that the precise behaviour is unstable.
In the docs for process::abort():
* Promise that we have the same behaviour as C `abort()`.
* Document the likely consequences, including, specifically, the consequences on Unix.
In the internal comment for unix::abort_internal:
* Refer to the public docs for the public API functions.
* Correct and expand the description of libc::abort. Specifically:
* Do not claim that abort() unregisters signal handlers. It doesn't; it honours the SIGABRT handler.
* Discuss, extensively, the issue with abort() flushing stdio buffers.
* Describe the glibc behaviour in some detail.
Co-authored-by: Mark Wooding <mdw@distorted.org.uk>
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
Fixes#40230
And withdraw the allegation of "abuse".
Adapted from a suggestion by @m-ou-se.
Co-authored-by: Mara Bos <m-ou.se@m-ou.se>
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
In the docs for intrinsics::abort():
* Strengthen the recommendation by to use process::abort instead.
* Document the fact that it (ab)uses an LLVM debug trap and what the
likely consequences are.
* State that the precise behaviour is unstable.
In the docs for process::abort():
* Promise that we have the same behaviour as C `abort()`.
* Document the likely consequences, including, specifically, the
consequences on Unix.
In the internal comment for unix::abort_internal:
* Refer to the public docs for the public API functions.
* Correct and expand the description of libc::abort. Specifically:
* Do not claim that abort() unregisters signal handlers. It doesn't;
it honours the SIGABRT handler.
* Discuss, extensively, the issue with abort() flushing stdio buffers.
* Describe the glibc behaviour in some detail.
Co-authored-by: Mark Wooding <mdw@distorted.org.uk>
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
Add examples to the various methods of `core::task::Poll`
This improves the documentation of the various methods of [`core::task::Poll`](https://doc.rust-lang.org/std/task/enum.Poll.html). These currently have fairly simple docs with no examples. This PR changes these methods to be closer to `core::option::Option` and adds usage examples (and importantly: tests!) to `Poll`'s methods.
cc/ `@rust-lang/wg-async-foundations`
## Screenshots
<details>
<summary>View generated rustdoc page</summary>
<image src="https://user-images.githubusercontent.com/2467194/123286616-59ee9b00-d50e-11eb-9e02-40269070f904.png" alt="Poll in core::task"></details>
core: add unstable no_fp_fmt_parse to disable float formatting code
In some projects (e.g. kernel), floating point is forbidden. They can disable
hardware floating point support and use `+soft-float` to avoid fp instructions
from being generated, but as libcore contains the formatting code for `f32`
and `f64`, some fp intrinsics are depended. One could define stubs for these
intrinsics that just panic [1], but it means that if any formatting functions
are accidentally used, mistake can only be caught during the runtime rather
than during compile-time or link-time, and they consume a lot of space without
LTO.
This patch provides an unstable cfg `no_fp_fmt_parse` to disable these.
A panicking stub is still provided for the `Debug` implementation (unfortunately)
because there are some SIMD types that use `#[derive(Debug)]`.
[1]: https://lkml.org/lkml/2021/4/14/1028
Stabilize `str::from_utf8_unchecked` as `const`
This stabilizes `unsafe fn str::from_utf8_unchecked` as `const` pending FCP on #75196. By the time FCP finishes, the beta will have already been cut, so I've set 1.55 as the stable-since version.
(should also be +relnotes but I don't have the permission to do that)
r? `@m-ou-se`
Closes#75196
In some projects (e.g. kernel), floating point is forbidden. They can disable
hardware floating point support and use `+soft-float` to avoid fp instructions
from being generated, but as libcore contains the formatting code for `f32`
and `f64`, some fp intrinsics are depended. One could define stubs for these
intrinsics that just panic [1], but it means that if any formatting functions
are accidentally used, mistake can only be caught during the runtime rather
than during compile-time or link-time, and they consume a lot of space without
LTO.
This patch provides an unstable cfg `no_fp_fmt_parse` to disable these.
A panicking stub is still provided for the `Debug` implementation (unfortunately)
because there are some SIMD types that use `#[derive(Debug)]`.
[1]: https://lkml.org/lkml/2021/4/14/1028
Use HTTPS links where possible
While looking at #86583, I wondered how many other (insecure) HTTP links were in `rustc`. This changes most other `http` links to `https`. While most of the links are in comments or documentation, there are a few other HTTP links that are used by CI that are changed to HTTPS.
Notes:
- I didn't change any to or in licences
- Some links don't support HTTPS :(
- Some `http` links were dead, in those cases I upgraded them to their new places (all of which used HTTPS)
Use `#[non_exhaustive]` where appropriate
Due to the std/alloc split, it is not possible to make `alloc::collections::TryReserveError::AllocError` non-exhaustive without having an unstable, doc-hidden method to construct (which negates the benefits from `#[non_exhaustive]`).
`@rustbot` label +C-cleanup +T-libs +S-waiting-on-review
(Most of these are from a review by joshtriplett. Thanks!)
Fix errors in `as_pin_ref` and `as_pin_mut` in the "Adapters for
working with references" overview.
Reword some headings about transformation methods.
Reclassify `map`, `map_or`, `map_or_else`, `map_err`, etc. to more
accurately reflect which variants they transform.
Document `Debug` requirement for `get_or_insert_default`.
Reword text about `take` and `replace` to be more accurate.
Add examples for the `Product` and `Sum` traits.
Also:
Move link reference definitions closer to their uses. Warn about making
link reference definintions for `err` and `ok`. Avoid making other link
reference definitions that might conflict in the future (foreign methods
that share a name with local ones, etc.)
Write out the generics of `Option` and `Result` when the following
text refers to the type parameters.
Due to the std/alloc split, it is not possible to make
`alloc::collections::TryReserveError::AllocError` non-exhaustive without
having an unstable, doc-hidden method to construct (which negates the
benefits from `#[non_exhaustive]`.
Document associativity of iterator folds.
Document the associativity of `Iterator::fold` and
`DoubleEndedIterator::rfold` and add examples demonstrating this.
Add links to direct users to the fold of the opposite associativity.
Better errors for Debug and Display traits
Currently, if someone tries to pass value that does not implement `Debug` or `Display` to a formatting macro, they get a very verbose and confusing error message. This PR changes the error messages for missing `Debug` and `Display` impls to be less overwhelming in this case, as suggested by #85844. I was a little less aggressive in changing the error message than that issue proposed. Still, this implementation would be enough to reduce the number of messages to be much more manageable.
After this PR, information on the cause of an error involving a `Debug` or `Display` implementation would suppressed if the requirement originated within a standard library macro. My reasoning was that errors originating from within a macro are confusing when they mention details that the programmer can't see, and this is particularly problematic for `Debug` and `Display`, which are most often used via macros. It is possible that either a broader or a narrower criterion would be better. I'm quite open to any feedback.
Fixes#85844.
Add comments around code where ordering is important due for panic-safety
Iterators contain arbitrary code which may panic. Unsafe code has to be
careful to do its state updates at the right point between calls that may panic.
As requested in https://github.com/rust-lang/rust/pull/86452#discussion_r655153948
r? `@RalfJung`
Iterators contain arbitrary code which may panic. Unsafe code has to be
careful to do its state updates at the right point between calls
that may panic.
Rollup of 11 pull requests
Successful merges:
- #85054 (Revert SGX inline asm syntax)
- #85182 (Move `available_concurrency` implementation to `sys`)
- #86037 (Add `io::Cursor::{remaining, remaining_slice, is_empty}`)
- #86114 (Reopen#79692 (Format symbols under shared frames))
- #86297 (Allow to pass arguments to rustdoc-gui tool)
- #86334 (Resolve type aliases to the type they point to in intra-doc links)
- #86367 (Fix comment about rustc_inherit_overflow_checks in abs().)
- #86381 (Add regression test for issue #39161)
- #86387 (Remove `#[allow(unused_lifetimes)]` which is now unnecessary)
- #86398 (Add regression test for issue #54685)
- #86493 (Say "this enum variant takes"/"this struct takes" instead of "this function takes")
Failed merges:
r? `@ghost`
`@rustbot` modify labels: rollup
Add MIR pass to lower call to `core::slice::len` into `Len` operand
During some larger experiment with range analysis I've found that code like `let l = slice.len()` produces different MIR then one found in bound checks. This optimization pass replaces terminators that are calls to `core::slice::len` with just a MIR operand and Goto terminator.
It uses some heuristics to remove the outer borrow that is made to call `core::slice::len`, but I assume it can be eliminated, just didn't find how.
Would like to express my gratitude to `@oli-obk` who helped me a lot on Zullip
fix panic-safety in specialized Zip::next_back
This was unsound since a panic in a.next_back() would result in the
length not being updated which would then lead to the same element
being revisited in the side-effect preserving code.
fixes#86443
Alter std::cell::Cell::get_mut documentation
I felt that there was some inconsistency between between Cell and RefCell with regards to their `get_mut` method documentation: `RefCell` flags this method as "unusual" in that it takes `&mut self`, while `Cell` does not. I attempted to flag this in `Cell`s documentation as well, and point to `RefCell`s method in the case where it is required.
Find relevant parts of docs and the new version below.
The current docs for `Cell::get_mut`:
> Returns a mutable reference to the underlying data.
This call borrows Cell mutably (at compile-time) which guarantees that we possess the only reference.
And `RefCell::get_mut`:
> Returns a mutable reference to the underlying data.
This call borrows `RefCell` mutably (at compile-time) so there is no need for dynamic checks.
However be cautious: this method expects self to be mutable, which is generally not the case when using a `RefCell`. Take a look at the `borrow_mut` method instead if self isn’t mutable.
Also, please be aware that this method is only for special circumstances and is usually not what you want. In case of doubt, use `borrow_mut` instead.
My attempt to make `Cell::get_mut` clearer:
> Returns a mutable reference to the underlying data.
This call borrows `Cell` mutably (at compile-time) which guaranteesthat we possess the only reference.
However be cautious: this method expects `self` to be mutable, which is generally not the case when using a `Cell`. If you require interior mutability by reference, consider using `RefCell` which provides run-time checked mutable borrows through its `borrow_mut` method.
This was unsound since a panic in a.next_back() would result in the
length not being updated which would then lead to the same element
being revisited in the side-effect preserving code.
Document the associativity of `Iterator::fold` and
`DoubleEndedIterator::rfold` and add examples demonstrating this.
Add links to direct users to the fold of the opposite associativity.
Make `sum()` and `product()` documentation hyperlinks refer to `Iterator` methods.
The previous linking seemed confusing: within "the sum() method on iterators", "sum()" was linked to `Sum::sum`, not `Iterator::sum`, even though the sentence is talking about the latter. I have rewritten the sentence to be, I believe, clearer, as well as changing the link destinations; applying the same change to the `Product` documentation as well as `Sum`.
I reviewed other traits in the same module and did not see similar issues, and previewed the results using `./x.py doc library/std`.
This method on the Iterator trait is doc(hidden), and about half of
implementations were doc(hidden). This adds the attribute to the
remaining implementations.
The previous linking seemed confusing: within "the sum() method on
iterators", "sum()" was linked to `Sum::sum`, not `Iterator::sum`, even
though the sentence is talking about the latter.
I have rewritten the sentence to be, I believe, clearer, as well as
changing the link destinations; applying the same change to the
`Product` documentation as well as `Sum`.
Mention the `Borrow` guarantee on the `Hash` implementations for Arrays and `Vec`
To remind people like me who forget about it and send PRs to make them different, and to (probably) get a test failure if the code is changed to no longer uphold it.
Updates `Clone` docs for `Copy` comparison.
Quite a few people (myself included) have come under the impression that the difference between `Copy` and `Clone` is that `Copy` is cheap and `Clone` is expensive, where the actual difference is that `Copy` constrains the type to bit-wise copying, and `Clone` allows for more expensive operations. The source of this misconception is in the `Clone` docs, where the following line is in the description:
> Differs from `Copy` in that `Copy` is implicit and extremely inexpensive, while `Clone` is always explicit and may or may not be expensive.
The `Clone` documentation page also comes up before the `Copy` page on google when searching for "the difference between `Clone` and `Copy`".
This PR updates the documentation to clarify that "extremely inexpensive" means an "inexpensive bit-wise copy" to hopefully prevent future rust users from falling into this misunderstanding.
Integrate binary search codes of binary_search_by and partition_point
For now partition_point has own binary search code piece.
It is because binary_search_by had called the comparer more times and the author (=me) wanted to avoid it.
However, now binary_search_by uses the comparer minimum times. (#74024)
So it's time to integrate them.
The appearance of the codes are a bit different but both use completely same logic.
Stabilize {std, core}::prelude::rust_*.
This stabilizes the `{core, std}::prelude::{rust_2015, rust_2018, rust_2021}` modules.
The usage of these modules as the prelude in those editions was already stabilized. This just stabilizes the modules themselves, making it possible for a user to explicitly refer to them.
Tracking issue: https://github.com/rust-lang/rust/issues/85684
FCP on the RFC that included this finished here: https://github.com/rust-lang/rfcs/pull/3114#issuecomment-840577395
Add functions `Duration::try_from_secs_{f32, f64}`
These functions allow constructing a Duration from a floating point value that could be out of range without panicking.
Tracking issue: #83400
Revert #85176 addition of `clone_from` for `ManuallyDrop`
Forwarding `clone_from` to the inner value changes the observable behavior, as previously the inner value would *not* be dropped by the default implementation.
Frankly, this is a super-niche case, so #85176 is welcome to argue the behavior should be otherwise! But if we overrride it, IMO documenting the behavior would be good.
Example: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2018&gist=c5d0856686fa850c1d7ee16891014efb
Make minor wording changes in a few places. Move `filter` to the
"transformations" section. Add `zip` methods to the "transformations"
section. Clarify the section about `Option` iterators, and add a section
about collecting into `Option`.
Clarify that for `Result`, `or` and `or_else` can also produce a
`Result` having a different type.
