diff options
| author | Guillaume Gomez <guillaume1.gomez@gmail.com> | 2024-05-27 13:10:33 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-05-27 13:10:33 +0200 |
| commit | 6dddc888fcdb0849ebf1fe4241bffa9b2a2c0812 (patch) | |
| tree | c270290beb30c4e48a7da61ee8d0197abe7a3c72 | |
| parent | b582f807fae230b22ac126ff1d8a13262bb099ba (diff) | |
| parent | 9b480da36790ea8314b77cf97ecaf7653afb3a1a (diff) | |
| download | rust-6dddc888fcdb0849ebf1fe4241bffa9b2a2c0812.tar.gz rust-6dddc888fcdb0849ebf1fe4241bffa9b2a2c0812.zip | |
Rollup merge of #124870 - Lokathor:update-result-docs, r=dtolnay
Update Result docs to the new guarantees The `Option` docs already explain the guarantees given in [RFC 3391](https://github.com/rust-lang/rfcs/blob/master/text/3391-result_ffi_guarantees.md), so all that we need is a paragraph saying that some `Result` type combinations will also qualify. Part of https://github.com/rust-lang/rust/issues/110503
| -rw-r--r-- | library/core/src/option.rs | 3 | ||||
| -rw-r--r-- | library/core/src/result.rs | 21 |
2 files changed, 24 insertions, 0 deletions
diff --git a/library/core/src/option.rs b/library/core/src/option.rs index 1e3ed0f7c49..9a527073602 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -137,10 +137,13 @@ //! //! [^extern_fn]: this remains true for any argument/return types and any other ABI: `extern "abi" fn` (_e.g._, `extern "system" fn`) //! +//! Under some conditions the above types `T` are also null pointer optimized when wrapped in a [`Result`][result_repr]. +//! //! [`Box<U>`]: ../../std/boxed/struct.Box.html //! [`num::NonZero*`]: crate::num //! [`ptr::NonNull<U>`]: crate::ptr::NonNull //! [function call ABI]: ../primitive.fn.html#abi-compatibility +//! [result_repr]: crate::result#representation //! //! This is called the "null pointer optimization" or NPO. //! diff --git a/library/core/src/result.rs b/library/core/src/result.rs index 4c6dc4bba43..f8cdcc000c5 100644 --- a/library/core/src/result.rs +++ b/library/core/src/result.rs @@ -228,6 +228,27 @@ //! [`Err(E)`]: Err //! [io::Error]: ../../std/io/struct.Error.html "io::Error" //! +//! # Representation +//! +//! In some cases, [`Result<T, E>`] will gain the same size, alignment, and ABI +//! guarantees as [`Option<U>`] has. One of either the `T` or `E` type must be a +//! type that qualifies for the `Option` [representation guarantees][opt-rep], +//! and the *other* type must meet all of the following conditions: +//! * Is a zero-sized type with alignment 1 (a "1-ZST"). +//! * Has no fields. +//! * Does not have the `#[non_exhaustive]` attribute. +//! +//! For example, `NonZeroI32` qualifies for the `Option` representation +//! guarantees, and `()` is a zero-sized type with alignment 1, no fields, and +//! it isn't `non_exhaustive`. This means that both `Result<NonZeroI32, ()>` and +//! `Result<(), NonZeroI32>` have the same size, alignment, and ABI guarantees +//! as `Option<NonZeroI32>`. The only difference is the implied semantics: +//! * `Option<NonZeroI32>` is "a non-zero i32 might be present" +//! * `Result<NonZeroI32, ()>` is "a non-zero i32 success result, if any" +//! * `Result<(), NonZeroI32>` is "a non-zero i32 error result, if any" +//! +//! [opt-rep]: ../option/index.html#representation "Option Representation" +//! //! # Method overview //! //! In addition to working with pattern matching, [`Result`] provides a |