This has now been approved as a language feature and no longer needs
a `rustc_` prefix.
Also change the `contracts` feature to be marked as incomplete and
`contracts_internals` as internal.
1. Document the new intrinsics.
2. Make the intrinsics actually check the contract if enabled, and
remove `contract::check_requires` function.
3. Use panic with no unwind in case contract is using to check for
safety, we probably don't want to unwind. Following the same
reasoning as UB checks.
The extended syntax for function signature that includes contract clauses
should never be user exposed versus the interface we want to ship
externally eventually.
includes post-developed commit: do not suggest internal-only keywords as corrections to parse failures.
includes post-developed commit: removed tabs that creeped in into rustfmt tool source code.
includes post-developed commit, placating rustfmt self dogfooding.
includes post-developed commit: add backquotes to prevent markdown checking from trying to treat an attr as a markdown hyperlink/
includes post-developed commit: fix lowering to keep contracts from being erroneously inherited by nested bodies (like closures).
Rebase Conflicts:
- compiler/rustc_parse/src/parser/diagnostics.rs
- compiler/rustc_parse/src/parser/item.rs
- compiler/rustc_span/src/hygiene.rs
Remove contracts keywords from diagnostic messages
There was a macro parameter giving signed impls access to the
corresponding unsigned type, but not the other way around.
This will allow implementing methods converting in both directions.
rustc_allowed_through_unstable_modules: require deprecation message
This changes the `#[rustc_allowed_through_unstable_modules]` attribute so that a deprecation message (ideally directing people towards the stable path) is required.
Implement all mix/max functions in a (hopefully) more optimization amendable way
Previously the graph was like this:
```
min -> Ord::min -> min_by -> match on compare() (in these cases compare = Ord::cmp)
^
|
min_by_key
```
now it looks like this:
```
min -> Ord::min -> `<=` <- min_by_key
min_by -> `Ordering::is_le` of `compare()`
```
(`max*` and `minmax*` are the exact same, i.e. they also use `<=` and `is_le`)
I'm not sure how to test this, but it should probably be easier for the backend to optimize.
r? `@scottmcm`
cc https://github.com/rust-lang/rust/issues/115939#issuecomment-2622161134
Insert null checks for pointer dereferences when debug assertions are enabled
Similar to how the alignment is already checked, this adds a check
for null pointer dereferences in debug mode. It is implemented similarly
to the alignment check as a `MirPass`.
This inserts checks in the same places as the `CheckAlignment` pass and additionally
also inserts checks for `Borrows`, so code like
```rust
let ptr: *const u32 = std::ptr::null();
let val: &u32 = unsafe { &*ptr };
```
will have a check inserted on dereference. This is done because null references
are UB. The alignment check doesn't cover these places, because in `&(*ptr).field`,
the exact requirement is that the final reference must be aligned. This is something to
consider further enhancements of the alignment check.
For now this is implemented as a separate `MirPass`, to make it easy to disable
this check if necessary.
This is related to a 2025H1 project goal for better UB checks in debug
mode: https://github.com/rust-lang/rust-project-goals/pull/177.
r? `@saethlin`
Similar to how the alignment is already checked, this adds a check
for null pointer dereferences in debug mode. It is implemented similarly
to the alignment check as a MirPass.
This is related to a 2025H1 project goal for better UB checks in debug
mode: https://github.com/rust-lang/rust-project-goals/pull/177.
float::min/max: mention the non-determinism around signed 0
Turns out this can actually produce different results on different machines [in practice](https://github.com/rust-lang/rust/issues/83984#issuecomment-2623859230); that seems worth documenting. I assume LLVM will happily const-fold these operations so so there could be different results for the same input even on the same machine, depending on whether things get const-folded or not.
`@nikic` I remember there was an LLVM soundness fix regarding scalar evolution for loops that had to recognize certain operations as non-deterministic... it seems to me that pass would also have to avoid predicting the result of `llvm.{min,max}num`, for the same reason?
r? `@tgross35`
Cc `@rust-lang/libs-api`
If this lands we should also make Miri non-deterministic here.
Fixes https://github.com/rust-lang/rust/issues/83984
Stabilize `const_black_box`
This has been unstably const since #92226, but a tracking issue was never created. Per [discussion on Zulip][zulip], there should not be any blockers to making this const-stable. The function does not provide any functionality at compile time but does allow code reuse between const- and non-const functions, so stabilize it here.
[zulip]: https://rust-lang.zulipchat.com/#narrow/channel/146212-t-compiler.2Fconst-eval/topic/const_black_box
Remove minor future footgun in `impl Debug for MaybeUninit`
No longer breaks if `MaybeUninit` moves modules (technically it could break if `MaybeUninit` were renamed but realistically that will never happen)
Debug impl originally added in #133282
Add `AsyncFn*` to `core` prelude
In https://github.com/rust-lang/rust/pull/132611 these got added to the `std` prelude only, which looks like an oversight.
r? libs-api
cc `@compiler-errors`
Implement `int_from_ascii` (#134821)
Provides unstable `T::from_ascii()` and `T::from_ascii_radix()` for integer types `T`, as drafted in tracking issue #134821.
To deduplicate documentation without additional macros, implementations of `isize` and `usize` no longer delegate to equivalent integer types. After #132870 they are inlined anyway.
Cleanup docs for Allocator
This is an attempt to remove ungrammatical constructions and clean up the prose. I've sometimes had to try hard to understand what was being stated, so it is possible that I've misunderstood the original meaning. In particular, I did not see a difference between:
- the borrow-checker lifetime of the allocator type itself.
- as long as at least one of the allocator instance and all of its clones has not been dropped.
optimize slice::ptr_rotate for small rotates
r? `@scottmcm`
This swaps the positions and numberings of algorithms 1 and 2 in `slice::ptr_rotate`, and pulls the entire outer loop into algorithm 3 since it was redundant for the first two. Effectively, `ptr_rotate` now always does the `memcpy`+`memmove`+`memcpy` sequence if the shifts fit into the stack buffer.
With this change, an `IndexMap`-style `move_index` function is optimized correctly.
Assembly comparisons:
- `move_index`, before: https://godbolt.org/z/Kr616KnYM
- `move_index`, after: https://godbolt.org/z/1aoov6j8h
- the code from `#89714`, before: https://godbolt.org/z/Y4zaPxEG6
- the code from `#89714`, after: https://godbolt.org/z/1dPx83axc
related to #89714
some relevant discussion in https://internals.rust-lang.org/t/idea-shift-move-to-efficiently-move-elements-in-a-vec/22184
Behavior tests pass locally. I can't get any consistent microbenchmark results on my machine, but the assembly diffs look promising.
* Renames the methods:
* `get_many_mut` -> `get_disjoint_mut`
* `get_many_unchecked_mut` -> `get_disjoint_unchecked_mut`
* Does not rename the feature flag: `get_many_mut`
* Marks the feature as stable
* Renames some helper stuff:
* `GetManyMutError` -> `GetDisjointMutError`
* `GetManyMutIndex` -> `GetDisjointMutIndex`
* `get_many_mut_helpers` -> `get_disjoint_mut_helpers`
* `get_many_check_valid` -> `get_disjoint_check_valid`
This only touches slice methods.
HashMap's methods and feature gates are not renamed here
(nor are they stabilized).
Put the core unit tests in a separate coretests package
Having standard library tests in the same package as a standard library crate has bad side effects. It causes the test to have a dependency on a locally built standard library crate, while also indirectly depending on it through libtest. Currently this works out fine in the context of rust's build system as both copies are identical, but for example in cg_clif's tests I've found it basically impossible to compile both copies with the exact same compiler flags and thus the two copies would cause lang item conflicts.
This PR moves the tests of libcore to a separate package which doesn't depend on libcore, thus preventing the duplicate crates even when compiler flags don't exactly match between building the sysroot (for libtest) and building the test itself. The rest of the standard library crates do still have this issue however.
compiler_fence: fix example
The old example was wrong, an acquire fence is required in the signal handler. To make the point more clear, I changed the "data" variable to use non-atomic accesses.
Fixes https://github.com/rust-lang/rust/issues/133014
Rollup of 7 pull requests
Successful merges:
- #133631 (Support QNX 7.1 with `io-sock`+libstd and QNX 8.0 (`no_std` only))
- #134358 (compiler: Set `target_abi = "ilp32e"` on all riscv32e targets)
- #135812 (Fix GDB `OsString` provider on Windows )
- #135842 (TRPL: more backward-compatible Edition changes)
- #135946 (Remove extra whitespace from rustdoc breadcrumbs for copypasting)
- #135953 (ci.py: check the return code in `run-local`)
- #136019 (Add an `unchecked_div` alias to the `Div<NonZero<_>>` impls)
r? `@ghost`
`@rustbot` modify labels: rollup
Update emscripten std tests
This disables a bunch of emscripten tests that test things emscripten doesn't support and re-enables a whole bunch of tests which now work just fine on emscripten.
Tested with `EMCC_CFLAGS="-s MAXIMUM_MEMORY=2GB" ./x.py test library/ --target wasm32-unknown-emscripten`.
Fix `FormattingOptions` instantiation with `Default`
The `fill` value by default should be set to `' '` (space), but the current implementation uses `#[derive(Default)]` which sets it to `\0`.
Note that `FormattingOptions` is being released as part of 1.85 (unstable) - so this might warrant a backport to that branch.
Tracking issue: https://github.com/rust-lang/rust/issues/118117
Follow up from https://github.com/rust-lang/rust/pull/118159
CC: ``@EliasHolzmann`` ``@programmerjake``
r? ``@m-ou-se``
Add memory layout documentation to generic NonZero<T>
The documentation I've added is based on the same Layout documentation that appears on the other `NonZero*` types. For example see [the Layout docs on `NonZeroI8`](https://doc.rust-lang.org/std/num/type.NonZeroI8.html#layout-1).
remove pointless allowed_through_unstable_modules on TryFromSliceError
This got added in https://github.com/rust-lang/rust/pull/132482 but the PR does not explain why. `@lukas-code` do you still remember? Also Cc `@Noratrieb` as reviewer of that PR.
If I understand the issue description correctly, all paths under which this type is exported are stable now: `core::array::TryFromSliceError` and `std::array::TryFromSliceError`. If that is the case, we shouldn't have the attribute; it's a terrible hack that should only be used when needed to maintain backward compatibility. Getting some historic information right is IMO *not* sufficient justification to risk accidentally exposing this type via more unstable paths today or in the future.
Implement `ByteStr` and `ByteString` types
Approved ACP: https://github.com/rust-lang/libs-team/issues/502
Tracking issue: https://github.com/rust-lang/rust/issues/134915
These types represent human-readable strings that are conventionally,
but not always, UTF-8. The `Debug` impl prints non-UTF-8 bytes using
escape sequences, and the `Display` impl uses the Unicode replacement
character.
This is a minimal implementation of these types and associated trait
impls. It does not add any helper methods to other types such as `[u8]`
or `Vec<u8>`.
I've omitted a few implementations of `AsRef`, `AsMut`, and `Borrow`,
when those would be the second implementation for a type (counting the
`T` impl), to avoid potential inference failures. We can attempt to add
more impls later in standalone commits, and run them through crater.
In addition to the `bstr` feature, I've added a `bstr_internals` feature
for APIs provided by `core` for use by `alloc` but not currently
intended for stabilization.
This API and its implementation are based *heavily* on the `bstr` crate
by Andrew Gallant (`@BurntSushi).`
r? `@BurntSushi`
Add an example of using `carrying_mul_add` to write wider multiplication
Just the basic quadratic version that you wouldn't actually use for really-big integers, but it's nice and short so is useful as for a demonstration of why you might find `carrying_mul_add` useful :)
cc #85532 ``````@clarfonthey``````
Enable `unreachable_pub` lint in core
This PR enables the [`unreachable_pub`](https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#unreachable-pub) as warn in `core`, `rtstartup` and `panic_unwind`.
The motivation is similar to the compiler [MCP: Enable deny(unreachable_pub) on `rustc_*` crates](https://github.com/rust-lang/compiler-team/issues/773#issue-2467219005) :
> "Where is this thing used?" is a question I ask all the time when reading unfamiliar code. Because of this, I generally find it annoying when things are marked with a more permissive visibility than necessary. "This thing marked pub, which other crates is it used in? Oh, it's not used in any other crates."
Another motivation is to help to lint by utilizing it in-tree and seeing it's limitation in more complex scenarios.
The diff was mostly generated with `./x.py fix --stage 1 library/core/ -- --broken-code`, as well as manual edits for code in macros, generated code and other targets.
r? libs
Reexport likely/unlikely in std::hint
Since `likely`/`unlikely` should be working now, we could reexport them in `std::hint`. I'm not sure if this is already approved or if it requires approval
Tracking issue: #26179
Improve `select_nth_unstable` documentation clarity
* Instead uses `before` and `after` variable names in the example
where `greater` and `lesser` are flipped.
* Uses `<=` and `>=` instead of "less than or equal to" and "greater
than or equal to" to make the docs more concise.
* General attempt to remove unnecessary words and be more precise. For
example it seems slightly wrong to say "its final sorted position",
since this implies there is only one sorted position for this element.
[cfg_match] Adjust syntax
A year has passed since the creation of #115585 and the feature, as expected, is not moving forward. Let's change that.
This PR proposes changing the arm's syntax from `cfg(SOME_CONDITION) => { ... }` to `SOME_CODITION => {}`.
```rust
match_cfg! {
unix => {
fn foo() { /* unix specific functionality */ }
}
target_pointer_width = "32" => {
fn foo() { /* non-unix, 32-bit functionality */ }
}
_ => {
fn foo() { /* fallback implementation */ }
}
}
```
Why? Because after several manual migrations in https://github.com/rust-lang/rust/pull/116342 it became clear, at least for me, that `cfg` prefixes are unnecessary, verbose and redundant.
Again, everything is just a proposal to move things forward. If the shown syntax isn't ideal, feel free to close this PR or suggest other alternatives.
Rollup of 5 pull requests
Successful merges:
- #135497 (fix typo in typenames of pin documentation)
- #135522 (add incremental test for issue 135514)
- #135523 (const traits: remove some known-bug that do not seem to make sense)
- #135535 (Add GUI test for #135499)
- #135541 (Methods of const traits are const)
r? `@ghost`
`@rustbot` modify labels: rollup
fix typo in typenames of pin documentation
I noticed this whilst reading the documentation for pin.
Basically there was just one to many closing angle brackets on the type parameters in the documentation where instead of being `Pin<&mut T>` it was `Pin<&mut T>>`
deprecate `std::intrinsics::transmute` etc, use `std::mem::*` instead
The `rustc_allowed_through_unstable_modules` attribute lets users call `std::mem::transmute` as `std::intrinsics::transmute`. The former is a reexport of the latter, and for a long time we didn't properly check stability for reexports, so making this a hard error now would be a breaking change for little gain. But at the same time, `std::intrinsics::transmute` is not the intended path for this function, so I think it is a good idea to show a deprecation warning when that path is used. This PR implements that, for all the functions in `std::intrinsics` that carry the attribute.
I assume this will need ``@rust-lang/libs-api`` FCP.
Rollup of 7 pull requests
Successful merges:
- #132397 (Make missing_abi lint warn-by-default.)
- #133807 (ci: Enable opt-dist for dist-aarch64-linux builds)
- #134143 (Convert `struct FromBytesWithNulError` into enum)
- #134338 (Use a C-safe return type for `__rust_[ui]128_*` overflowing intrinsics)
- #134678 (Update `ReadDir::next` in `std::sys::pal::unix::fs` to use `&raw const (*p).field` instead of `p.byte_offset().cast()`)
- #135424 (Detect unstable lint docs that dont enable their feature)
- #135520 (Make sure we actually use the right trivial lifetime substs when eagerly monomorphizing drop for ADTs)
r? `@ghost`
`@rustbot` modify labels: rollup
Convert `struct FromBytesWithNulError` into enum
This PR renames the former `kind` enum from `FromBytesWithNulErrorKind` to `FromBytesWithNulError`, and removes the original struct.
See https://github.com/rust-lang/libs-team/issues/493
## Possible Changes - TBD
* [x] should the new `enum FromBytesWithNulError` derive `Copy`?
* [ ] should there be any new/changed attributes?
* [x] add some more tests
## Problem
One of `CStr` constructors, `CStr::from_bytes_with_nul(bytes: &[u8])` handles 3 cases:
1. `bytes` has one NULL as the last value - creates CStr
2. `bytes` has no NULL - error
3. `bytes` has a NULL in some other position - error
The 3rd case is error that may require lossy conversion, but the 2nd case can easily be handled by the user code. Unfortunately, this function returns an opaque `FromBytesWithNulError` error in both 2nd and 3rd case, so the user cannot detect just the 2nd case - having to re-implement the entire function and bring in the `memchr` dependency.
## Motivating examples or use cases
In [this code](f86d7a8768/varnish-sys/src/vcl/ws.rs (L158)), my FFI code needs to copy user's `&[u8]` into a C-allocated memory blob in a NUL-terminated `CStr` format. My code must first validate if `&[u8]` has a trailing NUL (case 1), no NUL (adds one on the fly - case 2), or NUL in the middle (3rd case - error). I had to re-implement `from_bytes_with_nul` and add `memchr`dependency just to handle the 2nd case.
r? `@Amanieu`
Add #[inline] to copy_from_slice
I'm doing cooked things to CGU partitioning for compiler-builtins (https://github.com/rust-lang/rust/pull/135395) and this was the lone symbol in my compiler-builtins rlib that wasn't an intrinsic. Adding `#[inline]` makes it go away.
Perf report indicates a marginal but chaotic effect on compile time, marginal improvement in codegen. As expected.
update and clarify StructuralPartialEq docs
This apparently hasn't been updated when we finalized the current const pattern matching behavior.
Fixes https://github.com/rust-lang/rust/issues/92454 by providing rationale and context in the docs linked from that error message.
One of `CStr` constructors, `CStr::from_bytes_with_nul(bytes: &[u8])` handles 3 cases:
1. `bytes` has one NULL as the last value - creates CStr
2. `bytes` has no NULL - error
3. `bytes` has a NULL in some other position - error
The 3rd case is error that may require lossy conversion, but the 2nd case can easily be handled by the user code. Unfortunately, this function returns an opaque `FromBytesWithNulError` error in both 2nd and 3rd case, so the user cannot detect just the 2nd case - having to re-implement the entire function and bring in the `memchr` dependency.
In [this code](f86d7a8768/varnish-sys/src/vcl/ws.rs (L158)), my FFI code needs to copy user's `&[u8]` into a C-allocated memory blob in a NUL-terminated `CStr` format. My code must first validate if `&[u8]` has a trailing NUL (case 1), no NUL (adds one on the fly - case 2), or NUL in the middle (3rd case - error). I had to re-implement `from_bytes_with_nul` and add `memchr`dependency just to handle the 2nd case.
This PR renames the former `kind` enum from `FromBytesWithNulErrorKind` to `FromBytesWithNulError`, and removes the original struct.
Use `NonNull::without_provenance` within the standard library
This API removes the need for several `unsafe` blocks, and leads to clearer code. It uses feature `nonnull_provenance` (#135243).
Close#135343
Update a bunch of library types for MCP807
This greatly reduces the number of places that actually use the `rustc_layout_scalar_valid_range_*` attributes down to just 3:
```
library/core\src\ptr\non_null.rs
68:#[rustc_layout_scalar_valid_range_start(1)]
library/core\src\num\niche_types.rs
19: #[rustc_layout_scalar_valid_range_start($low)]
20: #[rustc_layout_scalar_valid_range_end($high)]
```
Everything else -- PAL Nanoseconds, alloc's `Cap`, niched FDs, etc -- all just wrap those `niche_types` types.
r? ghost
Approved ACP: https://github.com/rust-lang/libs-team/issues/502
Tracking issue: https://github.com/rust-lang/rust/issues/134915
These types represent human-readable strings that are conventionally,
but not always, UTF-8. The `Debug` impl prints non-UTF-8 bytes using
escape sequences, and the `Display` impl uses the Unicode replacement
character.
This is a minimal implementation of these types and associated trait
impls. It does not add any helper methods to other types such as `[u8]`
or `Vec<u8>`.
I've omitted a few implementations of `AsRef`, `AsMut`, `Borrow`,
`From`, and `PartialOrd`, when those would be the second implementation
for a type (counting the `T` impl) or otherwise may cause inference
failures. These impls are important, but we can attempt to add them
later in standalone commits, and run them through crater.
In addition to the `bstr` feature, I've added a `bstr_internals` feature
for APIs provided by `core` for use by `alloc` but not currently
intended for stabilization.
This API and its implementation are based *heavily* on the `bstr` crate
by Andrew Gallant (@BurntSushi).
This greatly reduces the number of places that actually use the `rustc_layout_scalar_valid_range_*` attributes down to just 3:
```
library/core\src\ptr\non_null.rs
68:#[rustc_layout_scalar_valid_range_start(1)]
library/core\src\num\niche_types.rs
19: #[rustc_layout_scalar_valid_range_start($low)]
20: #[rustc_layout_scalar_valid_range_end($high)]
```
Everything else -- PAL Nanoseconds, alloc's `Cap`, niched FDs, etc -- all just wrap those `niche_types` types.
Fix `ptr::from_ref` documentation example comment
The comment says that the expression involves no function call, but that was only true for the example above, the example here _does_ contain a function call.
``@rustbot`` label A-docs
Improve prose around `as_slice` example of IterMut
I've removed the cryptic message about not being able to call `&mut self` methods while retaining a shared borrow of the iterator, such as `as_slice` produces. This is just normal borrowing rules and does not seem especially relevant here. I can whip up a replacement if someone thinks it has value.
[generic_assert] Constify methods used by the formatting system
cc #44838
Starts the "constification" of all the elements required to allow the execution of the formatting system in constant environments.
```rust
const _: () = { panic!("{:?}", 1i32); };
```
Further stuff is blocked by #133999.
The implementation is unsound when a partially consumed iterator has
some elements buffered in the front/back parts and cloning the Iterator
removes the capacity from the backing vec::IntoIter.
char to_digit: avoid unnecessary casts to u64
Hello,
in the `char::to_digit` method there are a few `as u64` casts that are not strictly necessary.
I assume that the reason behind these casts is to avoid possible overflows in the `+ 10` add.
This PR removes the aforementioned casts, avoiding the overflow issue by slightly modifying the ASCII letter to int mapping.
Thanks,
Happy new year.
* Instead uses `before` and `after` variable names in the example
where `greater` and `lesser` are flipped.
* Uses `<=` and `>=` instead of "less than or equal to" and "greater
than or equal to" to make the docs more concise.
* General attempt to remove unnecessary words and be more precise. For
example it seems slightly wrong to say "its final sorted position",
since this implies there is only one sorted position for this element.
Tidy up bigint multiplication methods
This tidies up the library version of the bigint multiplication methods after the addition of the intrinsics in #133663. It follows [this summary](https://github.com/rust-lang/rust/issues/85532#issuecomment-2403442775) of what's desired for these methods.
Note that, if `2H = N`, then `uH::MAX * uH::MAX + uH::MAX + uH::MAX` is `uN::MAX`, and that we can effectively add two "carry" values without overflowing.
For ease of terminology, the "low-order" or "least significant" or "wrapping" half of multiplication will be called the low part, and the "high-order" or "most significant" or "overflowing" half of multiplication will be called the high part. In all cases, the return convention is `(low, high)` and left unchanged by this PR, to be litigated later.
## API Changes
The original API:
```rust
impl uN {
// computes self * rhs
pub const fn widening_mul(self, rhs: uN) -> (uN, uN);
// computes self * rhs + carry
pub const fn carrying_mul(self, rhs: uN, carry: uN) -> (uN, uN);
}
```
The added API:
```rust
impl uN {
// computes self * rhs + carry1 + carry2
pub const fn carrying2_mul(self, rhs: uN, carry: uN, add: uN) -> (uN, uN);
}
impl iN {
// note that the low part is unsigned
pub const fn widening_mul(self, rhs: iN) -> (uN, iN);
pub const fn carrying_mul(self, rhs: iN, carry: iN) -> (uN, iN);
pub const fn carrying_mul_add(self, rhs: iN, carry: iN, add: iN) -> (uN, iN);
}
```
Additionally, a naive implementation has been added for `u128` and `i128` since there are no double-wide types for those. Eventually, an intrinsic will be added to make these more efficient, but rather than doing this all at once, the library changes are added first.
## Justifications for API
The unsigned parts are done to ensure consistency with overflowing addition: for a two's complement integer, you want to have unsigned overflow semantics for all parts of the integer except the highest one. This is because overflow for unsigned integers happens on the highest bit (from `MAX` to zero), whereas overflow for signed integers happens on the second highest bit (from `MAX` to `MIN`). Since the sign information only matters in the highest part, we use unsigned overflow for everything but that part.
There is still discussion on the merits of signed bigint *addition* methods, since getting the behaviour right is very subtle, but at least for signed bigint *multiplication*, the sign of the operands does make a difference. So, it feels appropriate that at least until we've nailed down the final API, there should be an option to do signed versions of these methods.
Additionally, while it's unclear whether we need all three versions of bigint multiplication (widening, carrying-1, and carrying-2), since it's possible to have up to two carries without overflow, there should at least be a method to allow that. We could potentially only offer the carry-2 method and expect that adding zero carries afterword will optimise correctly, but again, this can be litigated before stabilisation.
## Note on documentation
While a lot of care was put into the documentation for the `widening_mul` and `carrying_mul` methods on unsigned integers, I have not taken this same care for `carrying_mul_add` or the signed versions. While I have updated the doc tests to be more appropriate, there will likely be many documentation changes done before stabilisation.
## Note on tests
Alongside this change, I've added several tests to ensure that these methods work as expected. These are alongside the codegen tests for the intrinsics.
Fix doc for read&write unaligned in zst operation
### PR Description
This PR addresses an inconsistency in the Rust documentation regarding `read_unaligned ` and `write_unaligned` on zero-sized types (ZSTs). The current documentation for [pointer validity](https://doc.rust-lang.org/nightly/std/ptr/index.html#safety) states that for zero-sized types (ZSTs), null pointers are valid:
> For zero-sized types (ZSTs), every pointer is valid, including the null pointer.
However, there is an inconsistency in the documentation for the unaligned read operation in the function [ptr::read_unaligned](https://doc.rust-lang.org/nightly/std/ptr/fn.read_unaligned.html)(as well as `write_unaligned`), which states:
> Note that even if T has size 0, the pointer must be non-null.
This change is also supported by [PR #134912](https://github.com/rust-lang/rust/pull/134912)
> the _unaligned method docs should be fixed.
ptr docs: make it clear that we are talking only about memory accesses
This should make it harder to take this sentence out of context and misunderstand it.
stabilize const_swap
libs-api FCP passed in https://github.com/rust-lang/rust/issues/83163.
However, I only just realized that this actually involves an intrinsic. The intrinsic could be implemented entirely with existing stable const functionality, but we choose to make it a primitive to be able to detect more UB. So nominating for `@rust-lang/lang` to make sure they are aware; I leave it up to them whether they want to FCP this.
While at it I also renamed the intrinsic to make the "nonoverlapping" constraint more clear.
Fixes#83163
The comment says that the expression involves no function call, but
that was only true for the example above, the example here _does_
contain a function call.
Provides unstable `T::from_ascii()` and `T::from_ascii_radix()` for integer
types `T`, as drafted in tracking issue #134821.
To deduplicate documentation without additional macros, implementations of
`isize` and `usize` no longer delegate to equivalent integer types.
After #132870 they are inlined anyway.
Add a compiler intrinsic to back `bigint_helper_methods`
cc https://github.com/rust-lang/rust/issues/85532
This adds a new `carrying_mul_add` intrinsic, to implement `wide_mul` and `carrying_mul`.
It has fallback MIR for all types -- including `u128`, which isn't currently supported on nightly -- so that it'll continue to work on all backends, including CTFE.
Then it's overridden in `cg_llvm` to use wider intermediate types, including `i256` for `u128::carrying_mul`.
ptr::copy: fix docs for the overlapping case
Fixes https://github.com/rust-lang/unsafe-code-guidelines/issues/549
As discussed in that issue, it doesn't make any sense for `copy` to read a byte via `src` after it was already written via `dst`. The entire point of this method is that is copies correctly even if they overlap, and that requires always reading any given location before writing it.
Cc `@rust-lang/opsem`
docs: inline `std::ffi::c_str` types to `std::ffi`
Rustdoc has no way to show that an item is stable, but only at a different path. `std::ffi::c_str::NulError` is not stable, but `std::ffi::NulError` is.
To avoid marking these types as unstable when someone just wants to follow a link from `CString`, inline them into their stable paths.
Fixes#134702
r? `@tgross35`
Update Code Example for `Iterator::rposition`
Added an additional assertion to the example to show the behavior of `iter.next_back` after using `iter.rposition`.
