Document why `Range*<&T> as RangeBounds<T>` impls are not `T: ?Sized`, and give an alternative.
`Range*<&T> as RangeBounds<T>` impls have been tried to be relaxed to `T: ?Sized` at least twice:
* https://github.com/rust-lang/rust/pull/61584
* https://github.com/rust-lang/rust/pull/64327
I also was just about to make another PR to do it again until I `./x.py test library/alloc` and rediscovered the type inference regression, then searched around and found the previous PRs. Hence this PR instead so hopefully that doesn't keep happening 😛.
These impls cannot be relaxed for two reasons:
1. Type inference regressions: See ``@SimonSapin's`` explanation from a previous PR: https://github.com/rust-lang/rust/pull/61584#issuecomment-499601046
2. It's a breaking change: `impl RangeBounds<MyUnsizedType> for std::ops::Range<&MyUnsizedType>` is allowed after the coherence rebalance ([playground link](https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=f704a6fe53bfc33e55b2fc246d895ec2)), and relaxing these impls would conflict with that downstream impl.
This PR adds doc-comments explaining that not having `T: ?Sized` is intentional[^1], and gives an explicit alternative: `(Bound<&T>, Bound<&T>)`.
Technically, the impls for the unstable new `std::range` types could be relaxed, as they are still unstable so the change would not be breaking, but having them be different in this regard seems worse (and the non-iterable `RangeTo/RangeToInclusive` range types are shared between the "new" and "old" so cannot be changed anyway), and then the type inference regression would pop up in whatever edition the new range types stabilize in.
The "see \<link\> for discussion of those issues" is intentionally left as a non-doc comment just for whoever may try to relax these impls again in the future, but if it is preferred to have the link in the docs I can add that.
Closes https://github.com/rust-lang/rust/issues/107196 (as wontfix)
CC https://github.com/rust-lang/rust/issues/64027
[^1]: "intentional" is maybe a bit of strong wording, should it instead say something like "was stabilized without it and it would be breaking to change it now"?
fixed typo chunks->as_chunks
Fixesrust-lang/rust#144555
info-:
fix typo chunks -> as_chunks
This now take us to as_chunks page when clicking on as_chunks link and not to chunks .
Thanks .
constify with_exposed_provenance
We allow `int as ptr` in const, so it only makes sense to also allow this function. Otherwise, `const fn` can't be ported to use the more explicit exposed provenance APIs.
Note that as of today, `with_exposed_provenance` in const is equivalent to `without_provenance`. However, we probably don't want to promise that: if someone does `with_exposed_provenance(MMIO_ADDR)` in const and then uses that pointer at runtime, that is something we should ensure keeps working; if someone does the same with `without_provenance` then I would consider that UB.
Tracking: https://github.com/rust-lang/rust/issues/144538
Cc `````@rust-lang/wg-const-eval````` `````@rust-lang/opsem`````
Add `core::mem::DropGuard`
## 1.0 Summary
This PR introduces a new type `core::mem::DropGuard` which wraps a value and runs a closure when the value is dropped.
```rust
use core::mem::DropGuard;
// Create a new guard around a string that will
// print its value when dropped.
let s = String::from("Chashu likes tuna");
let mut s = DropGuard::new(s, |s| println!("{s}"));
// Modify the string contained in the guard.
s.push_str("!!!");
// The guard will be dropped here, printing:
// "Chashu likes tuna!!!"
```
## 2.0 Motivation
A number of programming languages include constructs like `try..finally` or `defer` to run code as the last piece of a particular sequence, regardless of whether an error occurred. This is typically used to clean up resources, like closing files, freeing memory, or unlocking resources. In Rust we use the `Drop` trait instead, allowing us to [never having to manually close sockets](https://blog.skylight.io/rust-means-never-having-to-close-a-socket/).
While `Drop` (and RAII in general) has been working incredibly well for Rust in general, sometimes it can be a little verbose to setup. In particular when upholding invariants are local to functions, having a quick inline way to setup an `impl Drop` can be incredibly convenient. We can see this in use in the Rust stdlib, which has a number of private `DropGuard` impls used internally:
- [library/alloc/src/vec/drain.rs](9982d6462b/library/alloc/src/vec/drain.rs (L177))
- [library/alloc/src/boxed/thin.rs](9982d6462b/library/alloc/src/boxed/thin.rs (L362))
- [library/alloc/src/slice.rs](9982d6462b/library/alloc/src/slice.rs (L413))
- [library/alloc/src/collections/linked_list.rs](9982d6462b/library/alloc/src/collections/linked_list.rs (L1135))
- [library/alloc/src/collections/binary_heap/mod.rs](9982d6462b/library/alloc/src/collections/binary_heap/mod.rs (L1816))
- [library/alloc/src/collections/btree/map.rs](9982d6462b/library/alloc/src/collections/btree/map.rs (L1715))
- [library/alloc/src/collections/vec_deque/drain.rs](9982d6462b/library/alloc/src/collections/vec_deque/drain.rs (L95))
- [library/alloc/src/vec/into_iter.rs](9982d6462b/library/alloc/src/vec/into_iter.rs (L488))
- [library/std/src/os/windows/process.rs](9982d6462b/library/std/src/os/windows/process.rs (L320))
- [tests/ui/process/win-proc-thread-attributes.rs](9982d6462b/tests/ui/process/win-proc-thread-attributes.rs (L17))
## 3.0 Design
This PR implements what can be considered about the simplest possible design:
1. A single type `DropGuard` which takes both a generic type `T` and a closure `F`.
2. `Deref` + `DerefMut` impls to make it easy to work with the `T` in the guard.
3. An `impl Drop` on the guard which calls the closure `F` on drop.
4. An inherent `fn into_inner` which takes the type `T` out of the guard without calling the closure `F`.
Notably this design does not allow divergent behavior based on the type of drop that has occurred. The [`scopeguard` crate](https://docs.rs/scopeguard/latest/scopeguard/index.html) includes additional `on_success` and `on_onwind` variants which can be used to branch on unwind behavior instead. However [in a lot of cases](https://github.com/rust-lang/rust/issues/143612#issuecomment-3053928328) this doesn’t seem necessary, and using the arm/disarm pattern seems to provide much the same functionality:
```rust
let guard = DropGuard::new((), |s| ...); // 1. Arm the guard
other_function(); // 2. Perform operations
guard.into_inner(); // 3. Disarm the guard
```
`DropGuard` combined with this pattern seems like it should cover the vast majority of use cases for quick, inline destructors. It certainly seems like it should cover all existing uses in the stdlib, as well as all existing uses in crates like [hashbrown](https://github.com/search?q=repo%3Arust-lang%2Fhashbrown%20guard&type=code).
## 4.0 Acknowledgements
This implementation is based on the [mini-scopeguard crate](https://github.com/yoshuawuyts/mini-scopeguard) which in turn is based on the [scopeguard crate](https://docs.rs/scopeguard). The implementations only differ superficially; because of the nature of the problem there is only really one obvious way to structure the solution. And the scopeguard crate got that right!
## 5.0 Conclusion
This PR adds a new type `core::mem::DropGuard` to the stdlib which adds a small convenience helper to create inline destructors with. This would bring the majority of the functionality of the `scopeguard` crate into the stdlib, which is the [49th most downloaded crate](https://crates.io/crates?sort=downloads) on crates.io (387 million downloads).
Given the actual implementation of `DropGuard` is only around 60 lines, it seems to hit that sweet spot of low-complexity / high-impact that makes for a particularly efficient stdlib addition. Which is why I’m putting this forward for consideration; thanks!
Fix CI for drop_guard
fix CI
fix all tidy lints
fix tidy link
add first batch of feedback from review
Add second batch of feedback from review
add third batch of feedback from review
fix failing test
Update library/core/src/mem/drop_guard.rs
Co-authored-by: Ruby Lazuli <general@patchmixolydic.com>
fix doctests
Implement changes from T-Libs-API review
And start tracking based on the tracking issue.
fix tidy lint
str: Mark unstable `round_char_boundary` feature functions as const
Mark `floor_char_boundary`, `ceil_char_boundary` const
Simplify the implementations, reducing the number of arithmetic operations
It seems unnecessary to do the lower/upper bounds calculations and extra slicing when we can jump straight to inspecting the bytes, assuming the underlying data is valid UTF-8.
Tracking issue https://github.com/rust-lang/rust/issues/93743
This leads tools like rustfmt to get confused, because the doc code
block effectively spans two doc comments. As a result, the tools think
the first code block is unclosed, and the subsequent terminator opens a
new block.
Move the FIXME comments outside the doc code blocks, instead.
Because doc code does not get automatically formatted, some doc code has
creative placements of comments that automatic formatting can't handle.
Reformat those comments to make the resulting code support standard Rust
formatting without breaking; this is generally an improvement to
readability as well.
Some comments are not indented to the prevailing indent, and are instead
aligned under some bit of code. Indent them to the prevailing indent,
and put spaces *inside* the comments to align them with code.
Some comments span several lines of code (which aren't the line the
comment is about) and expect alignment. Reformat them into one comment
not broken up by unrelated intervening code.
Some comments are placed on the same line as an opening brace, placing
them effectively inside the subsequent block, such that formatting would
typically format them like a line of that block. Move those comments to
attach them to what they apply to.
Some comments are placed on the same line as a one-line braced block,
effectively attaching them to the closing brace, even though they're
about the code inside the block. Reformat to make sure the comment will
stay on the same line as the code it's commenting.
Hint that choose_pivot returns index in bounds
Instead of using `unsafe` in multiple places, one `hint::assert_unchecked` allows use of safe code instead.
Part of #rust-lang/rust#144326
flt2dec: replace for loop by iter_mut
Perf is explored in https://github.com/rust-lang/rust/issues/144118, which initially showed small losses, but then also showed significant gains. Both are real, but given the smallness of the losses, this seems a good change.
address clippy formatting nits
- int_log10.rs: change top level doc comments to outer
- collect.rs: remove empty line after doc comment
- clippy fix: markdown indentation for indented items after line break: a markdown list item continued over multiples lines, but those following lines which are part of the same item are not indented
- clippy fix: bound in one place: when there is a bound in angle brackets and another bound on the same variable in a where clause
Remove deprecated `MaybeUninit` slice methods
These were left in to make migration a bit easier, although they should be removed now since they were never stable.
