From 73ada2d40429488aaaacf37b608bababc137b910 Mon Sep 17 00:00:00 2001 From: Laurence Tratt Date: Wed, 12 Aug 2020 15:07:38 +0100 Subject: [PATCH] Explicitly document the size guarantees that Option makes. Triggered by a discussion on wg-unsafe-code-guidelines about which layouts of `Option` one can guarantee are optimised to a single pointer. --- library/core/src/option.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/library/core/src/option.rs b/library/core/src/option.rs index 3c7211fe040..745b0f1ae8d 100644 --- a/library/core/src/option.rs +++ b/library/core/src/option.rs @@ -70,10 +70,18 @@ //! } //! ``` //! -//! This usage of [`Option`] to create safe nullable pointers is so -//! common that Rust does special optimizations to make the -//! representation of [`Option`]`<`[`Box`]`>` a single pointer. Optional pointers -//! in Rust are stored as efficiently as any other pointer type. +//! # Representation +//! +//! Rust guarantees to optimise the following inner types such that an [`Option`] which contains +//! them has the same size as a pointer: +//! +//! * `&T` +//! * `&mut T` +//! * `extern "C" fn` +//! * [`num::NonZero*`] +//! * [`ptr::NonNull`] +//! * `#[repr(transparent)]` struct around one of the types in this list. +//! * [`Box`] //! //! # Examples //!