document when atomic loads are guaranteed read-only
Based on this [discussion in Zulip](https://rust-lang.zulipchat.com/#narrow/stream/136281-t-opsem/topic/Can.20.60Atomic*.3A.3Aload.60.20perform.20a.20write).
The values for x86 and x86_64 are complete guesswork on my side, and I have no clue what the values might be for other architectures. I hope we can get the right people to chime in to gather the required information. :)
I'll update Miri to respect these rules once we have more data.
This makes it so that all the matchers that match against paths use the
definition path instead of the export path. This removes all duplication
around `std`/`alloc`/`core`.
This is not necessarily optimal because we now depend on internal
implementation details like `core::ops::control_flow::ControlFlow`,
which is not very nice and probably not acceptable for a stable
`on_unimplemented`.
An alternative would be to just string-replace normalize away
`alloc`/`core` to `std` as a special case, keeping the export paths but
making it so that we're still fully standard library flavor agnostic.
Stabilize `{IpAddr, Ipv6Addr}::to_canonical`
Make `IpAddr::to_canonical` and `IpV6Addr::to_canonical` stable (+const), as well as const stabilize `Ipv6Addr::to_ipv4_mapped`.
Newly stable API:
```rust
impl IpAddr {
// Newly stable under `ip_to_canonical`
const fn to_canonical(&self) -> IpAddr;
}
impl Ipv6Addr {
// Newly stable under `ip_to_canonical`
const fn to_canonical(&self) -> IpAddr;
// Already stable, this makes it const stable under
// `const_ipv6_to_ipv4_mapped`
const fn to_ipv4_mapped(&self) -> Option<Ipv4Addr>
}
```
These stabilize a subset of the following tracking issues:
- https://github.com/rust-lang/rust/issues/27709
- https://github.com/rust-lang/rust/issues/76205
Stabilization of all methods under the `ip` gate was attempted once at https://github.com/rust-lang/rust/pull/66584 then again at https://github.com/rust-lang/rust/pull/76098. These were not successful because there are still unknowns about `is_documentation` `is_benchmarking` and similar; `to_canonical` is much more straightforward.
I have looked and could not find any known issues with `to_canonical`. These were added in 2021 in https://github.com/rust-lang/rust/pull/87708
cc implementor ``@the8472``
r? libs-api
``@rustbot`` label +T-libs-api +needs-fcp
impl Not, Bit{And,Or}{,Assign} for IP addresses
ACP: rust-lang/libs-team#235
Note: since these are insta-stable, these require an FCP.
Implements, where `N` is either `4` or `6`:
```rust
impl Not for IpvNAddr
impl Not for &IpvNAddr
impl BitAnd<IpvNAddr> for IpvNAddr
impl BitAnd<&IpvNAddr> for IpvNAddr
impl BitAnd<IpvNAddr> for &IpvNAddr
impl BitAnd<&IpvNAddr> for &IpvNAddr
impl BitAndAssign<IpvNAddr> for IpvNAddr
impl BitAndAssign<&IpvNAddr> for IpvNAddr
impl BitOr<IpvNAddr> for IpvNAddr
impl BitOr<&IpvNAddr> for IpvNAddr
impl BitOr<IpvNAddr> for &IpvNAddr
impl BitOr<&IpvNAddr> for &IpvNAddr
impl BitOrAssign<IpvNAddr> for IpvNAddr
impl BitOrAssign<&IpvNAddr> for IpvNAddr
```
Implement FusedIterator for DecodeUtf16 when the inner iterator does
I have just implemented an iterator that wraps `DecodeUtf16` and wanted to implement `FusedIterator` for my iterator when I noticed that `DecodeUtf16` currently doesn't implement `FusedIterator` at all.
A quick look at the code of `DecodeUtf16` revealed that `DecodeUtf16::next` only returns `None` when its inner iterator returns `None`:
3462f79e94/library/core/src/char/decode.rs (L45)
As a result, we can implement `FusedIterator` for `DecodeUtf16` when the inner iterator does.
I'm following the example of #96397 here and consider this change minor and non-controversial, which is why I haven't added an RFC. I have also added the required feature name (`"decode_utf16_fused_iterator"`), however without adding a chapter to the Rust Unstable book (same as #96397).
optimize zipping over array iterators
Fixes#115339 (somewhat)
the new assembly:
```asm
zip_arrays:
.cfi_startproc
vmovups (%rdx), %ymm0
leaq 32(%rsi), %rcx
vxorps %xmm1, %xmm1, %xmm1
vmovups %xmm1, -24(%rsp)
movq $0, -8(%rsp)
movq %rsi, -88(%rsp)
movq %rdi, %rax
movq %rcx, -80(%rsp)
vmovups %ymm0, -72(%rsp)
movq $0, -40(%rsp)
movq $32, -32(%rsp)
movq -24(%rsp), %rcx
vmovups (%rsi,%rcx), %ymm0
vorps -72(%rsp,%rcx), %ymm0, %ymm0
vmovups %ymm0, (%rsi,%rcx)
vmovups (%rsi), %ymm0
vmovups %ymm0, (%rdi)
vzeroupper
retq
```
This is still longer than the slice version given in the issue but at least it eliminates the terrible `vpextrb`/`orb` chain. I guess this is due to excessive memcpys again (haven't looked at the llvmir)?
The `TrustedLen` specialization is a drive-by change since I had to do something for the default impl anyway to be able to specialize the `TrustedRandomAccessNoCoerce` impl.
* Remove duplicate alignment note that mentioned `AtomicBool` with other
types
* Update safety requirements about when non-atomic operations are
allowed
Implement `slice::split_once` and `slice::rsplit_once`
Feature gate is `slice_split_once` and tracking issue is #112811. These are equivalents to the existing `str::split_once` and `str::rsplit_once` methods.
Fix generic bound of `str::SplitInclusive`'s `DoubleEndedIterator` impl
`str::SplitInclusive`'s `DoubleEndedIterator` implementation currently uses a `ReverseSearcher` bound for the corresponding searcher. A `DoubleEndedSearcher` bound should have been used instead.
`DoubleEndedIterator` requires that repeated `next_back` calls produce the same items as repeated `next` calls, in opposite order. `ReverseSearcher` lets you search starting from the back of a string, but it makes no guarantees about how its matches correspond to the matches found by a forward search. `DoubleEndedSearcher` is a subtrait of `ReverseSearcher` and does require that the same matches are found in both directions.
This bug fix is a breaking change. Calling `next_back` on `"a+++b".split_inclusive("++")` is currently accepted with repeated calls producing `"b"` and `"a+++"`, while forward iteration yields `"a++"` and `"+b"`. Also see https://github.com/rust-lang/rust/issues/100756#issuecomment-1221307166 for more details.
I believe that this is the only iterator that uses this bound incorrectly — other related iterators such as `str::Split` do have a `DoubleEndedSearcher` bound for their `DoubleEndedIterator` implementation. And `slice::SplitInclusive` doesn't face this problem at all because it doesn't use patterns, only a predicate.
cc `@SkiFire13`
Reuse existing `Some`s in `Option::(x)or`
LLVM still has trouble re-using discriminants sometimes when rebuilding a two-variant enum, so when we have the correct variant already built, just use it.
That's shorter in the Rust code, as well as simpler in MIR and the optimized LLVM, so might as well: <https://rust.godbolt.org/z/KhdE8eToW>
Thanks to `@veber-alex` for pointing out this opportunity in https://github.com/rust-lang/rust/issues/101210#issuecomment-1732470941
Fix a comment in std::iter::successors
The `unfold` function have since #58062 been renamed to `from_fn`.
(I'm not sure if this whole comment is still useful—it's not like there are many iterators that *can't* be based on `from_fn`. Anyway, in its current form this comment is not correct, and it sent me into a half-hour research of what happened to `unfold` function, so I want to do *something* with it 🙃 deleting these three lines is a perfectly fine alternative, in my opinion.)
Clarify example in docs of str::char_slice
Just a one word improvement.
“Last” can be misread as meaning the last (third) instead of the previous (first).
LLVM still has trouble re-using discriminants sometimes when rebuilding a two-variant enum, so when we have the correct variant already built, just use it.
That's simpler in LLVM *and* in MIR, so might as well: <https://rust.godbolt.org/z/KhdE8eToW>
docs: Correct terminology in std::cmp
This PR is the result of some discussions on URLO:
* [Traits in `std::cmp` and mathematical terminology](https://users.rust-lang.org/t/traits-in-std-cmp-and-mathematical-terminology/69887)
* [Are poker hands `Ord` or `PartialOrd`?](https://users.rust-lang.org/t/are-poker-hands-ord-or-partialord/82644)
Arguably, the documentation currently isn't very precise regarding mathematical terminology. This can lead to misunderstandings of what `PartialEq`, `Eq`, `PartialOrd`, and `Ord` actually do.
While I believe this PR doesn't give any new API guarantees, it expliclitly mentions that `PartialEq::eq(a, b)` may return `true` for two distinct values `a` and `b` (i.e. where `a` and `b` are not equal in the mathematical sense). This leads to the consequence that `Ord` may describe a weak ordering instead of a total ordering.
In either case, I believe this PR should be thoroughly reviewed, ideally by someone with mathematical background to make sure the terminology is correct now, and also to ensure that no unwanted new API guarantees are made.
In particular, the following problems are addressed:
* Some clarifications regarding used (mathematical) terminology:
* Avoid using the terms "total equality" and "partial equality" in favor of "equivalence relation" and "partial equivalence relation", which are well-defined and unambiguous.
* Clarify that `Ordering` is an ordering between two values (and not an order in the mathematical sense).
* Avoid saying that `PartialEq` and `Eq` are "equality comparisons" because the terminology "equality comparison" could be misleading: it's possible to implement `PartialEq` and `Eq` for other (partial) equivalence relations, in particular for relations where `a == b` for some `a` and `b` even when `a` and `b` are not the same value.
* Added a section "Strict and non-strict partial orders" to document that the `<=` and `>=` operators do not correspond to non-strict partial orders.
* Corrected section "Corollaries" in documenation of `Ord` in regard to `<` only describing a strict total order in cases where `==` conforms to mathematical equality.
* ~~Added a section "Weak orders" to explain that `Ord` may also describe a weak order or total preorder, depending on how `PartialEq::eq` has been implemented.~~ (Removed, see [comment](https://github.com/rust-lang/rust/pull/103046#issuecomment-1279929676))
* Made documentation easier to understand:
* Explicitly state at the beginning of `PartialEq`'s documentation comment that implementing the trait will provide the `==` and `!=` operators.
* Added an easier to understand rule when to implement `Eq` in addition to `PartialEq`: "if it’s guaranteed that `PartialEq::eq(a, a)` always returns `true`."
* Explicitly mention in documentation of `Eq` that the properties "symmetric" and "transitive" are already required by `PartialEq`.
core library: Disable fpmath tests for i586 ...
This patch disables the floating-point epsilon test for i586 since x87 registers are too imprecise and can't produce the expected results.
Some clarifications regarding used (mathematical) terminology:
* Avoid using the terms "total equality" and "partial equality" in favor
of "equivalence relation" and "partial equivalence relation", which
are well-defined and unambiguous.
* Clarify that `Ordering` is an ordering between two values (and not an
order in the mathematical sense).
* Avoid saying that `PartialEq` and `Eq` are "equality comparisons"
because the terminology "equality comparison" could be misleading:
it's possible to implement `PartialEq` and `Eq` for other (partial)
equivalence relations, in particular for relations where `a == b` for
some `a` and `b` even when `a` and `b` are not the same value.
* Added a section "Strict and non-strict partial orders" to document
that the `<=` and `>=` operators do not correspond to non-strict
partial orders.
* Corrected section "Corollaries" in documenation of Ord in regard to
`<` only describing a strict total order in cases where `==` conforms
to mathematical equality.
Made documentation easier to understand:
* Explicitly state at the beginning of `PartialEq`'s documentation
comment that implementing the trait will provide the `==` and `!=`
operators.
* Added an easier to understand rule when to implement `Eq` in addition
to `PartialEq`: "if it’s guaranteed that `PartialEq::eq(a, a)` always
returns `true`."
* Explicitly mention in documentation of `Eq` that the properties
"symmetric" and "transitive" are already required by `PartialEq`.
Works around #115199 by temporarily disabling CFI for core and std CFI
violations to allow the user rebuild and use both core and std with CFI
enabled using the Cargo build-std feature.
Adapt `todo!` documentation to mention displaying custom values
Resolves#116130.
I copied from the [existing documentation](https://doc.rust-lang.org/std/macro.unimplemented.html) for `unimplemented!` more or less directly, down to the example trait used. I also took the liberty of fixing some formatting and typographical errors that I noticed.
Add `must_use` on pointer equality functions
`ptr == ptr` (like all use of `==`) has a similar warning, and these functions are simple convenience wrappers over that.
Correct misleading std::fmt::Binary example (#116165)
Nothing too crazy...
- Add two to the width specifier (so all 32 bits are correctly displayed)
- Pad out the compared string so the assert passes
- Add `// Note` comment highlighting the need for the extra width when using the `#` flag.
The exact contents (and placement?) of the note are, of course, highly bikesheddable.
Partially outline code inside the panic! macro
This outlines code inside the panic! macro in some cases. This is split out from https://github.com/rust-lang/rust/pull/115562 to exclude changes to rustc.
Add "integer square root" method to integer primitive types
For every suffix `N` among `8`, `16`, `32`, `64`, `128` and `size`, this PR adds the methods
```rust
const fn uN::isqrt() -> uN;
const fn iN::isqrt() -> iN;
const fn iN::checked_isqrt() -> Option<iN>;
```
to compute the [integer square root](https://en.wikipedia.org/wiki/Integer_square_root), addressing issue #89273.
The implementation is based on the [base 2 digit-by-digit algorithm](https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Binary_numeral_system_(base_2)) on Wikipedia, which after some benchmarking has proved to be faster than both binary search and Heron's/Newton's method. I haven't had the time to understand and port [this code](http://atoms.alife.co.uk/sqrt/SquareRoot.java) based on lookup tables instead, but I'm not sure whether it's worth complicating such a function this much for relatively little benefit.
