add examples of port 0 binding behavior
Was trying to find the method to specify the IP address but not the port, and there wasn't information easily accessible about it in the `TcpListener` or `SocketAddr`. Adding examples to `TcpListener` and `UdpSocket` for clarity.
Specialize ToString implementation for fmt::Arguments
Generates far fewer instructions by formatting into a String with `fmt::format` directly instead of going through the `fmt::Display` impl. This change is insta-stable.
Add a conversion from `&mut T` to `&mut UnsafeCell<T>`
Provides a safe way of downgrading an exclusive reference into an alias-able `&UnsafeCell<T>` reference.
ACP: https://github.com/rust-lang/libs-team/issues/198.
Change Vec examples to not assert exact capacity except where it is guaranteed
It was [brought up on discord](https://discord.com/channels/273534239310479360/818964227783262209/1107633959329878077) that the `Vec::into_boxed_slice` example contradicted the `Vec::with_capacity` docs in that the returned `Vec` might have _more_ capacity than requested.
So, to reduce confusion change all the `assert_eq!(vec.capacity(), _)` to `assert!(vec.capacity() >= _)`, except in 4 examples that have guaranteed capacities: `Vec::from_raw_parts`, `Vec::from_raw_parts_in`, `Vec::<()>::with_capacity`,`Vec::<(), _>::with_capacity_in`.
Don't claim `LocalKey::with` prevents a reference to be sent across threads
The documentation for `LocalKey` claims that `with` yields a reference that cannot be sent across threads, but this is false since you can easily do that with scoped threads. What it actually prevents is the reference from outliving the current thread.
(docs) Change "wanting" to "want"
Changing " If you’re wanting" to "If you want".
Wanting is not wrong, of course, but I think that "If you want" feels more natural to most readers.
Fix some misleading and copy-pasted `Pattern` examples
These examples were listed twice and also were confusable with doing a substring match instead of a any-of-set match.
Update doc for `PhantomData` to match code example
After https://github.com/rust-lang/rust/pull/106621, there is no longer a `T: 'a` annotation in the doc example, so update the text to match the code.
Stabilize const slice::split_at
This stabilizes the use of the following method in const context:
```rust
impl<T> [T] {
pub const fn split_at(&self, mid: usize) -> (&[T], &[T]);
}
```
cc tracking issue #101158
Implement `AsHandle`/`AsSocket` for `Arc`/`Rc`/`Box` on Windows
Implement the Windows counterpart to #97437 and #107317: Implement `AsHandle` and `AsSocket` for `Arc<T>`, `Rc<T>`, and `Box<T>`.
Add midpoint function for all integers and floating numbers
This pull-request adds the `midpoint` function to `{u,i}{8,16,32,64,128,size}`, `NonZeroU{8,16,32,64,size}` and `f{32,64}`.
This new function is analog to the [C++ midpoint](https://en.cppreference.com/w/cpp/numeric/midpoint) function, and basically compute `(a + b) / 2` with a rounding towards ~~`a`~~ negative infinity in the case of integers. Or simply said: `midpoint(a, b)` is `(a + b) >> 1` as if it were performed in a sufficiently-large signed integral type.
Note that unlike the C++ function this pull-request does not implement this function on pointers (`*const T` or `*mut T`). This could be implemented in a future pull-request if desire.
### Implementation
For `f32` and `f64` the implementation in based on the `libcxx` [one](18ab892ff7/libcxx/include/__numeric/midpoint.h (L65-L77)). I originally tried many different approach but all of them failed or lead me with a poor version of the `libcxx`. Note that `libstdc++` has a very similar one; Microsoft STL implementation is also basically the same as `libcxx`. It unfortunately doesn't seems like a better way exist.
For unsigned integers I created the macro `midpoint_impl!`, this macro has two branches:
- The first one take `$SelfT` and is used when there is no unsigned integer with at least the double of bits. The code simply use this formula `a + (b - a) / 2` with the arguments in the correct order and signs to have the good rounding.
- The second branch is used when a `$WideT` (at least double of bits as `$SelfT`) is provided, using a wider number means that no overflow can occur, this greatly improve the codegen (no branch and less instructions).
For signed integers the code basically forwards the signed numbers to the unsigned version of midpoint by mapping the signed numbers to their unsigned numbers (`ex: i8 [-128; 127] to [0; 255]`) and vice versa.
I originally created a version that worked directly on the signed numbers but the code was "ugly" and not understandable. Despite this mapping "overhead" the codegen is better than my most optimized version on signed integers.
~~Note that in the case of unsigned numbers I tried to be smart and used `#[cfg(target_pointer_width = "64")]` to determine if using the wide version was better or not by looking at the assembly on godbolt. This was applied to `u32`, `u64` and `usize` and doesn't change the behavior only the assembly code generated.~~
PhantomData: fix documentation wrt interaction with dropck
As far as I could find out, the `PhantomData`-dropck interaction *only* affects code using `may_dangle`. The documentation in the standard library has not been updated for 8 years and thus stems from a time when Rust still used "parametric dropck", before [RFC 1238](https://rust-lang.github.io/rfcs/1238-nonparametric-dropck.html). Back then what the docs said was correct, but with `may_dangle` dropck it stopped being entirely accurate and these days, with NLL, it is actively misleading.
Fixes https://github.com/rust-lang/rust/issues/102810
Fixes https://github.com/rust-lang/rust/issues/70841
Cc `@nikomatsakis` I hope what I am saying here is right.^^
Uplift `clippy::{drop,forget}_{ref,copy}` lints
This PR aims at uplifting the `clippy::drop_ref`, `clippy::drop_copy`, `clippy::forget_ref` and `clippy::forget_copy` lints.
Those lints are/were declared in the correctness category of clippy because they lint on useless and most probably is not what the developer wanted.
## `drop_ref` and `forget_ref`
The `drop_ref` and `forget_ref` lint checks for calls to `std::mem::drop` or `std::mem::forget` with a reference instead of an owned value.
### Example
```rust
let mut lock_guard = mutex.lock();
std::mem::drop(&lock_guard) // Should have been drop(lock_guard), mutex
// still locked
operation_that_requires_mutex_to_be_unlocked();
```
### Explanation
Calling `drop` or `forget` on a reference will only drop the reference itself, which is a no-op. It will not call the `drop` or `forget` method on the underlying referenced value, which is likely what was intended.
## `drop_copy` and `forget_copy`
The `drop_copy` and `forget_copy` lint checks for calls to `std::mem::forget` or `std::mem::drop` with a value that derives the Copy trait.
### Example
```rust
let x: i32 = 42; // i32 implements Copy
std::mem::forget(x) // A copy of x is passed to the function, leaving the
// original unaffected
```
### Explanation
Calling `std::mem::forget` [does nothing for types that implement Copy](https://doc.rust-lang.org/std/mem/fn.drop.html) since the value will be copied and moved into the function on invocation.
-----
Followed the instructions for uplift a clippy describe here: https://github.com/rust-lang/rust/pull/99696#pullrequestreview-1134072751
cc `@m-ou-se` (as T-libs-api leader because the uplifting was discussed in a recent meeting)
Simplify the implementation of iterators over slices of ZSTs
Currently, slice iterators over ZSTs store `end = start.wrapping_byte_add(len)`.
That's slightly convenient for `is_empty`, but kinda annoying for pretty much everything else -- see bugs like #42789, for example.
This PR instead changes it to just `end = ptr::invalid(len)` instead.
That's easier to think about (IMHO, at least) as well as easier to represent.
`next` is still to big to get inlined into the mir-opt/pre-codegen/ tests, but if I bump the inline threshold to force it to show the whole thing, this implementation is also less MIR:
```
> git diff --numstat
241 370 tests/mir-opt/pre-codegen/slice_iter.forward_loop.PreCodegen.after.mir
255 329 tests/mir-opt/pre-codegen/slice_iter.reverse_loop.PreCodegen.after.mir
184 216 tests/mir-opt/pre-codegen/slice_iter.slice_iter_mut_next_back.PreCodegen.after.mir
182 254 tests/mir-opt/pre-codegen/slice_iter.slice_iter_next.PreCodegen.after.mir
```
(That's ≈70 lines less for `Iter::next`, for example.)
r? `@ghost`
~~Built atop #111282, so draft until that lands.~~
Currently, slice iterators over ZSTs store `end = start.wrapping_byte_add(len)`.
That's slightly convenient for `is_empty`, but kinda annoying for pretty much everything else -- see bugs like 42789, for example.
This PR instead changes it to just `end = ptr::invalid(len)` instead.
That's easier to think about (IMHO, at least) as well as easier to represent.
Don't force include Windows goop when documenting
Why do we need to include all the windows bits on non-windows platforms? Let's try not doing that.
Possible alternative to #111394, if it works.
Fix incorrect implication of transmuting slices
transmute<&[u8]> would be useful and as a beginner it is confusing to see documents casually confuse the types of &[u8] and [u8; SZ]
