core/mem/
maybe_uninit.rs

1use crate::any::type_name;
2use crate::mem::ManuallyDrop;
3use crate::{fmt, intrinsics, ptr, slice};
4
5/// A wrapper type to construct uninitialized instances of `T`.
6///
7/// # Initialization invariant
8///
9/// The compiler, in general, assumes that a variable is properly initialized
10/// according to the requirements of the variable's type. For example, a variable of
11/// reference type must be aligned and non-null. This is an invariant that must
12/// *always* be upheld, even in unsafe code. As a consequence, zero-initializing a
13/// variable of reference type causes instantaneous [undefined behavior][ub],
14/// no matter whether that reference ever gets used to access memory:
15///
16/// ```rust,no_run
17/// # #![allow(invalid_value)]
18/// use std::mem::{self, MaybeUninit};
19///
20/// let x: &i32 = unsafe { mem::zeroed() }; // undefined behavior! ⚠️
21/// // The equivalent code with `MaybeUninit<&i32>`:
22/// let x: &i32 = unsafe { MaybeUninit::zeroed().assume_init() }; // undefined behavior! ⚠️
23/// ```
24///
25/// This is exploited by the compiler for various optimizations, such as eliding
26/// run-time checks and optimizing `enum` layout.
27///
28/// Similarly, entirely uninitialized memory may have any content, while a `bool` must
29/// always be `true` or `false`. Hence, creating an uninitialized `bool` is undefined behavior:
30///
31/// ```rust,no_run
32/// # #![allow(invalid_value)]
33/// use std::mem::{self, MaybeUninit};
34///
35/// let b: bool = unsafe { mem::uninitialized() }; // undefined behavior! ⚠️
36/// // The equivalent code with `MaybeUninit<bool>`:
37/// let b: bool = unsafe { MaybeUninit::uninit().assume_init() }; // undefined behavior! ⚠️
38/// ```
39///
40/// Moreover, uninitialized memory is special in that it does not have a fixed value ("fixed"
41/// meaning "it won't change without being written to"). Reading the same uninitialized byte
42/// multiple times can give different results. This makes it undefined behavior to have
43/// uninitialized data in a variable even if that variable has an integer type, which otherwise can
44/// hold any *fixed* bit pattern:
45///
46/// ```rust,no_run
47/// # #![allow(invalid_value)]
48/// use std::mem::{self, MaybeUninit};
49///
50/// let x: i32 = unsafe { mem::uninitialized() }; // undefined behavior! ⚠️
51/// // The equivalent code with `MaybeUninit<i32>`:
52/// let x: i32 = unsafe { MaybeUninit::uninit().assume_init() }; // undefined behavior! ⚠️
53/// ```
54/// On top of that, remember that most types have additional invariants beyond merely
55/// being considered initialized at the type level. For example, a `1`-initialized [`Vec<T>`]
56/// is considered initialized (under the current implementation; this does not constitute
57/// a stable guarantee) because the only requirement the compiler knows about it
58/// is that the data pointer must be non-null. Creating such a `Vec<T>` does not cause
59/// *immediate* undefined behavior, but will cause undefined behavior with most
60/// safe operations (including dropping it).
61///
62/// [`Vec<T>`]: ../../std/vec/struct.Vec.html
63///
64/// # Examples
65///
66/// `MaybeUninit<T>` serves to enable unsafe code to deal with uninitialized data.
67/// It is a signal to the compiler indicating that the data here might *not*
68/// be initialized:
69///
70/// ```rust
71/// use std::mem::MaybeUninit;
72///
73/// // Create an explicitly uninitialized reference. The compiler knows that data inside
74/// // a `MaybeUninit<T>` may be invalid, and hence this is not UB:
75/// let mut x = MaybeUninit::<&i32>::uninit();
76/// // Set it to a valid value.
77/// x.write(&0);
78/// // Extract the initialized data -- this is only allowed *after* properly
79/// // initializing `x`!
80/// let x = unsafe { x.assume_init() };
81/// ```
82///
83/// The compiler then knows to not make any incorrect assumptions or optimizations on this code.
84///
85/// You can think of `MaybeUninit<T>` as being a bit like `Option<T>` but without
86/// any of the run-time tracking and without any of the safety checks.
87///
88/// ## out-pointers
89///
90/// You can use `MaybeUninit<T>` to implement "out-pointers": instead of returning data
91/// from a function, pass it a pointer to some (uninitialized) memory to put the
92/// result into. This can be useful when it is important for the caller to control
93/// how the memory the result is stored in gets allocated, and you want to avoid
94/// unnecessary moves.
95///
96/// ```
97/// use std::mem::MaybeUninit;
98///
99/// unsafe fn make_vec(out: *mut Vec<i32>) {
100///     // `write` does not drop the old contents, which is important.
101///     unsafe { out.write(vec![1, 2, 3]); }
102/// }
103///
104/// let mut v = MaybeUninit::uninit();
105/// unsafe { make_vec(v.as_mut_ptr()); }
106/// // Now we know `v` is initialized! This also makes sure the vector gets
107/// // properly dropped.
108/// let v = unsafe { v.assume_init() };
109/// assert_eq!(&v, &[1, 2, 3]);
110/// ```
111///
112/// ## Initializing an array element-by-element
113///
114/// `MaybeUninit<T>` can be used to initialize a large array element-by-element:
115///
116/// ```
117/// use std::mem::{self, MaybeUninit};
118///
119/// let data = {
120///     // Create an uninitialized array of `MaybeUninit`.
121///     let mut data: [MaybeUninit<Vec<u32>>; 1000] = [const { MaybeUninit::uninit() }; 1000];
122///
123///     // Dropping a `MaybeUninit` does nothing, so if there is a panic during this loop,
124///     // we have a memory leak, but there is no memory safety issue.
125///     for elem in &mut data[..] {
126///         elem.write(vec![42]);
127///     }
128///
129///     // Everything is initialized. Transmute the array to the
130///     // initialized type.
131///     unsafe { mem::transmute::<_, [Vec<u32>; 1000]>(data) }
132/// };
133///
134/// assert_eq!(&data[0], &[42]);
135/// ```
136///
137/// You can also work with partially initialized arrays, which could
138/// be found in low-level datastructures.
139///
140/// ```
141/// use std::mem::MaybeUninit;
142///
143/// // Create an uninitialized array of `MaybeUninit`.
144/// let mut data: [MaybeUninit<String>; 1000] = [const { MaybeUninit::uninit() }; 1000];
145/// // Count the number of elements we have assigned.
146/// let mut data_len: usize = 0;
147///
148/// for elem in &mut data[0..500] {
149///     elem.write(String::from("hello"));
150///     data_len += 1;
151/// }
152///
153/// // For each item in the array, drop if we allocated it.
154/// for elem in &mut data[0..data_len] {
155///     unsafe { elem.assume_init_drop(); }
156/// }
157/// ```
158///
159/// ## Initializing a struct field-by-field
160///
161/// You can use `MaybeUninit<T>`, and the [`std::ptr::addr_of_mut`] macro, to initialize structs field by field:
162///
163/// ```rust
164/// use std::mem::MaybeUninit;
165/// use std::ptr::addr_of_mut;
166///
167/// #[derive(Debug, PartialEq)]
168/// pub struct Foo {
169///     name: String,
170///     list: Vec<u8>,
171/// }
172///
173/// let foo = {
174///     let mut uninit: MaybeUninit<Foo> = MaybeUninit::uninit();
175///     let ptr = uninit.as_mut_ptr();
176///
177///     // Initializing the `name` field
178///     // Using `write` instead of assignment via `=` to not call `drop` on the
179///     // old, uninitialized value.
180///     unsafe { addr_of_mut!((*ptr).name).write("Bob".to_string()); }
181///
182///     // Initializing the `list` field
183///     // If there is a panic here, then the `String` in the `name` field leaks.
184///     unsafe { addr_of_mut!((*ptr).list).write(vec![0, 1, 2]); }
185///
186///     // All the fields are initialized, so we call `assume_init` to get an initialized Foo.
187///     unsafe { uninit.assume_init() }
188/// };
189///
190/// assert_eq!(
191///     foo,
192///     Foo {
193///         name: "Bob".to_string(),
194///         list: vec![0, 1, 2]
195///     }
196/// );
197/// ```
198/// [`std::ptr::addr_of_mut`]: crate::ptr::addr_of_mut
199/// [ub]: ../../reference/behavior-considered-undefined.html
200///
201/// # Layout
202///
203/// `MaybeUninit<T>` is guaranteed to have the same size, alignment, and ABI as `T`:
204///
205/// ```rust
206/// use std::mem::MaybeUninit;
207/// assert_eq!(size_of::<MaybeUninit<u64>>(), size_of::<u64>());
208/// assert_eq!(align_of::<MaybeUninit<u64>>(), align_of::<u64>());
209/// ```
210///
211/// However remember that a type *containing* a `MaybeUninit<T>` is not necessarily the same
212/// layout; Rust does not in general guarantee that the fields of a `Foo<T>` have the same order as
213/// a `Foo<U>` even if `T` and `U` have the same size and alignment. Furthermore because any bit
214/// value is valid for a `MaybeUninit<T>` the compiler can't apply non-zero/niche-filling
215/// optimizations, potentially resulting in a larger size:
216///
217/// ```rust
218/// # use std::mem::MaybeUninit;
219/// assert_eq!(size_of::<Option<bool>>(), 1);
220/// assert_eq!(size_of::<Option<MaybeUninit<bool>>>(), 2);
221/// ```
222///
223/// If `T` is FFI-safe, then so is `MaybeUninit<T>`.
224///
225/// While `MaybeUninit` is `#[repr(transparent)]` (indicating it guarantees the same size,
226/// alignment, and ABI as `T`), this does *not* change any of the previous caveats. `Option<T>` and
227/// `Option<MaybeUninit<T>>` may still have different sizes, and types containing a field of type
228/// `T` may be laid out (and sized) differently than if that field were `MaybeUninit<T>`.
229/// `MaybeUninit` is a union type, and `#[repr(transparent)]` on unions is unstable (see [the
230/// tracking issue](https://github.com/rust-lang/rust/issues/60405)). Over time, the exact
231/// guarantees of `#[repr(transparent)]` on unions may evolve, and `MaybeUninit` may or may not
232/// remain `#[repr(transparent)]`. That said, `MaybeUninit<T>` will *always* guarantee that it has
233/// the same size, alignment, and ABI as `T`; it's just that the way `MaybeUninit` implements that
234/// guarantee may evolve.
235///
236/// Note that even though `T` and `MaybeUninit<T>` are ABI compatible it is still unsound to
237/// transmute `&mut T` to `&mut MaybeUninit<T>` and expose that to safe code because it would allow
238/// safe code to access uninitialized memory:
239///
240/// ```rust,no_run
241/// use core::mem::MaybeUninit;
242///
243/// fn unsound_transmute<T>(val: &mut T) -> &mut MaybeUninit<T> {
244///     unsafe { core::mem::transmute(val) }
245/// }
246///
247/// fn main() {
248///     let mut code = 0;
249///     let code = &mut code;
250///     let code2 = unsound_transmute(code);
251///     *code2 = MaybeUninit::uninit();
252///     std::process::exit(*code); // UB! Accessing uninitialized memory.
253/// }
254/// ```
255#[stable(feature = "maybe_uninit", since = "1.36.0")]
256// Lang item so we can wrap other types in it. This is useful for coroutines.
257#[lang = "maybe_uninit"]
258#[derive(Copy)]
259#[repr(transparent)]
260#[rustc_pub_transparent]
261pub union MaybeUninit<T> {
262    uninit: (),
263    value: ManuallyDrop<T>,
264}
265
266#[stable(feature = "maybe_uninit", since = "1.36.0")]
267impl<T: Copy> Clone for MaybeUninit<T> {
268    #[inline(always)]
269    fn clone(&self) -> Self {
270        // Not calling `T::clone()`, we cannot know if we are initialized enough for that.
271        *self
272    }
273}
274
275#[stable(feature = "maybe_uninit_debug", since = "1.41.0")]
276impl<T> fmt::Debug for MaybeUninit<T> {
277    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
278        // NB: there is no `.pad_fmt` so we can't use a simpler `format_args!("MaybeUninit<{..}>").
279        let full_name = type_name::<Self>();
280        let prefix_len = full_name.find("MaybeUninit").unwrap();
281        f.pad(&full_name[prefix_len..])
282    }
283}
284
285impl<T> MaybeUninit<T> {
286    /// Creates a new `MaybeUninit<T>` initialized with the given value.
287    /// It is safe to call [`assume_init`] on the return value of this function.
288    ///
289    /// Note that dropping a `MaybeUninit<T>` will never call `T`'s drop code.
290    /// It is your responsibility to make sure `T` gets dropped if it got initialized.
291    ///
292    /// # Example
293    ///
294    /// ```
295    /// use std::mem::MaybeUninit;
296    ///
297    /// let v: MaybeUninit<Vec<u8>> = MaybeUninit::new(vec![42]);
298    /// # // Prevent leaks for Miri
299    /// # unsafe { let _ = MaybeUninit::assume_init(v); }
300    /// ```
301    ///
302    /// [`assume_init`]: MaybeUninit::assume_init
303    #[stable(feature = "maybe_uninit", since = "1.36.0")]
304    #[rustc_const_stable(feature = "const_maybe_uninit", since = "1.36.0")]
305    #[must_use = "use `forget` to avoid running Drop code"]
306    #[inline(always)]
307    pub const fn new(val: T) -> MaybeUninit<T> {
308        MaybeUninit { value: ManuallyDrop::new(val) }
309    }
310
311    /// Creates a new `MaybeUninit<T>` in an uninitialized state.
312    ///
313    /// Note that dropping a `MaybeUninit<T>` will never call `T`'s drop code.
314    /// It is your responsibility to make sure `T` gets dropped if it got initialized.
315    ///
316    /// See the [type-level documentation][MaybeUninit] for some examples.
317    ///
318    /// # Example
319    ///
320    /// ```
321    /// use std::mem::MaybeUninit;
322    ///
323    /// let v: MaybeUninit<String> = MaybeUninit::uninit();
324    /// ```
325    #[stable(feature = "maybe_uninit", since = "1.36.0")]
326    #[rustc_const_stable(feature = "const_maybe_uninit", since = "1.36.0")]
327    #[must_use]
328    #[inline(always)]
329    #[rustc_diagnostic_item = "maybe_uninit_uninit"]
330    pub const fn uninit() -> MaybeUninit<T> {
331        MaybeUninit { uninit: () }
332    }
333
334    /// Creates a new `MaybeUninit<T>` in an uninitialized state, with the memory being
335    /// filled with `0` bytes. It depends on `T` whether that already makes for
336    /// proper initialization. For example, `MaybeUninit<usize>::zeroed()` is initialized,
337    /// but `MaybeUninit<&'static i32>::zeroed()` is not because references must not
338    /// be null.
339    ///
340    /// Note that if `T` has padding bytes, those bytes are *not* preserved when the
341    /// `MaybeUninit<T>` value is returned from this function, so those bytes will *not* be zeroed.
342    ///
343    /// Note that dropping a `MaybeUninit<T>` will never call `T`'s drop code.
344    /// It is your responsibility to make sure `T` gets dropped if it got initialized.
345    ///
346    /// # Example
347    ///
348    /// Correct usage of this function: initializing a struct with zero, where all
349    /// fields of the struct can hold the bit-pattern 0 as a valid value.
350    ///
351    /// ```rust
352    /// use std::mem::MaybeUninit;
353    ///
354    /// let x = MaybeUninit::<(u8, bool)>::zeroed();
355    /// let x = unsafe { x.assume_init() };
356    /// assert_eq!(x, (0, false));
357    /// ```
358    ///
359    /// This can be used in const contexts, such as to indicate the end of static arrays for
360    /// plugin registration.
361    ///
362    /// *Incorrect* usage of this function: calling `x.zeroed().assume_init()`
363    /// when `0` is not a valid bit-pattern for the type:
364    ///
365    /// ```rust,no_run
366    /// use std::mem::MaybeUninit;
367    ///
368    /// enum NotZero { One = 1, Two = 2 }
369    ///
370    /// let x = MaybeUninit::<(u8, NotZero)>::zeroed();
371    /// let x = unsafe { x.assume_init() };
372    /// // Inside a pair, we create a `NotZero` that does not have a valid discriminant.
373    /// // This is undefined behavior. ⚠️
374    /// ```
375    #[inline]
376    #[must_use]
377    #[rustc_diagnostic_item = "maybe_uninit_zeroed"]
378    #[stable(feature = "maybe_uninit", since = "1.36.0")]
379    #[rustc_const_stable(feature = "const_maybe_uninit_zeroed", since = "1.75.0")]
380    pub const fn zeroed() -> MaybeUninit<T> {
381        let mut u = MaybeUninit::<T>::uninit();
382        // SAFETY: `u.as_mut_ptr()` points to allocated memory.
383        unsafe { u.as_mut_ptr().write_bytes(0u8, 1) };
384        u
385    }
386
387    /// Sets the value of the `MaybeUninit<T>`.
388    ///
389    /// This overwrites any previous value without dropping it, so be careful
390    /// not to use this twice unless you want to skip running the destructor.
391    /// For your convenience, this also returns a mutable reference to the
392    /// (now safely initialized) contents of `self`.
393    ///
394    /// As the content is stored inside a `ManuallyDrop`, the destructor is not
395    /// run for the inner data if the MaybeUninit leaves scope without a call to
396    /// [`assume_init`], [`assume_init_drop`], or similar. Code that receives
397    /// the mutable reference returned by this function needs to keep this in
398    /// mind. The safety model of Rust regards leaks as safe, but they are
399    /// usually still undesirable. This being said, the mutable reference
400    /// behaves like any other mutable reference would, so assigning a new value
401    /// to it will drop the old content.
402    ///
403    /// [`assume_init`]: Self::assume_init
404    /// [`assume_init_drop`]: Self::assume_init_drop
405    ///
406    /// # Examples
407    ///
408    /// Correct usage of this method:
409    ///
410    /// ```rust
411    /// use std::mem::MaybeUninit;
412    ///
413    /// let mut x = MaybeUninit::<Vec<u8>>::uninit();
414    ///
415    /// {
416    ///     let hello = x.write((&b"Hello, world!").to_vec());
417    ///     // Setting hello does not leak prior allocations, but drops them
418    ///     *hello = (&b"Hello").to_vec();
419    ///     hello[0] = 'h' as u8;
420    /// }
421    /// // x is initialized now:
422    /// let s = unsafe { x.assume_init() };
423    /// assert_eq!(b"hello", s.as_slice());
424    /// ```
425    ///
426    /// This usage of the method causes a leak:
427    ///
428    /// ```rust
429    /// use std::mem::MaybeUninit;
430    ///
431    /// let mut x = MaybeUninit::<String>::uninit();
432    ///
433    /// x.write("Hello".to_string());
434    /// # // FIXME(https://github.com/rust-lang/miri/issues/3670):
435    /// # // use -Zmiri-disable-leak-check instead of unleaking in tests meant to leak.
436    /// # unsafe { MaybeUninit::assume_init_drop(&mut x); }
437    /// // This leaks the contained string:
438    /// x.write("hello".to_string());
439    /// // x is initialized now:
440    /// let s = unsafe { x.assume_init() };
441    /// ```
442    ///
443    /// This method can be used to avoid unsafe in some cases. The example below
444    /// shows a part of an implementation of a fixed sized arena that lends out
445    /// pinned references.
446    /// With `write`, we can avoid the need to write through a raw pointer:
447    ///
448    /// ```rust
449    /// use core::pin::Pin;
450    /// use core::mem::MaybeUninit;
451    ///
452    /// struct PinArena<T> {
453    ///     memory: Box<[MaybeUninit<T>]>,
454    ///     len: usize,
455    /// }
456    ///
457    /// impl <T> PinArena<T> {
458    ///     pub fn capacity(&self) -> usize {
459    ///         self.memory.len()
460    ///     }
461    ///     pub fn push(&mut self, val: T) -> Pin<&mut T> {
462    ///         if self.len >= self.capacity() {
463    ///             panic!("Attempted to push to a full pin arena!");
464    ///         }
465    ///         let ref_ = self.memory[self.len].write(val);
466    ///         self.len += 1;
467    ///         unsafe { Pin::new_unchecked(ref_) }
468    ///     }
469    /// }
470    /// ```
471    #[inline(always)]
472    #[stable(feature = "maybe_uninit_write", since = "1.55.0")]
473    #[rustc_const_stable(feature = "const_maybe_uninit_write", since = "1.85.0")]
474    pub const fn write(&mut self, val: T) -> &mut T {
475        *self = MaybeUninit::new(val);
476        // SAFETY: We just initialized this value.
477        unsafe { self.assume_init_mut() }
478    }
479
480    /// Gets a pointer to the contained value. Reading from this pointer or turning it
481    /// into a reference is undefined behavior unless the `MaybeUninit<T>` is initialized.
482    /// Writing to memory that this pointer (non-transitively) points to is undefined behavior
483    /// (except inside an `UnsafeCell<T>`).
484    ///
485    /// # Examples
486    ///
487    /// Correct usage of this method:
488    ///
489    /// ```rust
490    /// use std::mem::MaybeUninit;
491    ///
492    /// let mut x = MaybeUninit::<Vec<u32>>::uninit();
493    /// x.write(vec![0, 1, 2]);
494    /// // Create a reference into the `MaybeUninit<T>`. This is okay because we initialized it.
495    /// let x_vec = unsafe { &*x.as_ptr() };
496    /// assert_eq!(x_vec.len(), 3);
497    /// # // Prevent leaks for Miri
498    /// # unsafe { MaybeUninit::assume_init_drop(&mut x); }
499    /// ```
500    ///
501    /// *Incorrect* usage of this method:
502    ///
503    /// ```rust,no_run
504    /// use std::mem::MaybeUninit;
505    ///
506    /// let x = MaybeUninit::<Vec<u32>>::uninit();
507    /// let x_vec = unsafe { &*x.as_ptr() };
508    /// // We have created a reference to an uninitialized vector! This is undefined behavior. ⚠️
509    /// ```
510    ///
511    /// (Notice that the rules around references to uninitialized data are not finalized yet, but
512    /// until they are, it is advisable to avoid them.)
513    #[stable(feature = "maybe_uninit", since = "1.36.0")]
514    #[rustc_const_stable(feature = "const_maybe_uninit_as_ptr", since = "1.59.0")]
515    #[rustc_as_ptr]
516    #[inline(always)]
517    pub const fn as_ptr(&self) -> *const T {
518        // `MaybeUninit` and `ManuallyDrop` are both `repr(transparent)` so we can cast the pointer.
519        self as *const _ as *const T
520    }
521
522    /// Gets a mutable pointer to the contained value. Reading from this pointer or turning it
523    /// into a reference is undefined behavior unless the `MaybeUninit<T>` is initialized.
524    ///
525    /// # Examples
526    ///
527    /// Correct usage of this method:
528    ///
529    /// ```rust
530    /// use std::mem::MaybeUninit;
531    ///
532    /// let mut x = MaybeUninit::<Vec<u32>>::uninit();
533    /// x.write(vec![0, 1, 2]);
534    /// // Create a reference into the `MaybeUninit<Vec<u32>>`.
535    /// // This is okay because we initialized it.
536    /// let x_vec = unsafe { &mut *x.as_mut_ptr() };
537    /// x_vec.push(3);
538    /// assert_eq!(x_vec.len(), 4);
539    /// # // Prevent leaks for Miri
540    /// # unsafe { MaybeUninit::assume_init_drop(&mut x); }
541    /// ```
542    ///
543    /// *Incorrect* usage of this method:
544    ///
545    /// ```rust,no_run
546    /// use std::mem::MaybeUninit;
547    ///
548    /// let mut x = MaybeUninit::<Vec<u32>>::uninit();
549    /// let x_vec = unsafe { &mut *x.as_mut_ptr() };
550    /// // We have created a reference to an uninitialized vector! This is undefined behavior. ⚠️
551    /// ```
552    ///
553    /// (Notice that the rules around references to uninitialized data are not finalized yet, but
554    /// until they are, it is advisable to avoid them.)
555    #[stable(feature = "maybe_uninit", since = "1.36.0")]
556    #[rustc_const_stable(feature = "const_maybe_uninit_as_mut_ptr", since = "1.83.0")]
557    #[rustc_as_ptr]
558    #[inline(always)]
559    pub const fn as_mut_ptr(&mut self) -> *mut T {
560        // `MaybeUninit` and `ManuallyDrop` are both `repr(transparent)` so we can cast the pointer.
561        self as *mut _ as *mut T
562    }
563
564    /// Extracts the value from the `MaybeUninit<T>` container. This is a great way
565    /// to ensure that the data will get dropped, because the resulting `T` is
566    /// subject to the usual drop handling.
567    ///
568    /// # Safety
569    ///
570    /// It is up to the caller to guarantee that the `MaybeUninit<T>` really is in an initialized
571    /// state. Calling this when the content is not yet fully initialized causes immediate undefined
572    /// behavior. The [type-level documentation][inv] contains more information about
573    /// this initialization invariant.
574    ///
575    /// [inv]: #initialization-invariant
576    ///
577    /// On top of that, remember that most types have additional invariants beyond merely
578    /// being considered initialized at the type level. For example, a `1`-initialized [`Vec<T>`]
579    /// is considered initialized (under the current implementation; this does not constitute
580    /// a stable guarantee) because the only requirement the compiler knows about it
581    /// is that the data pointer must be non-null. Creating such a `Vec<T>` does not cause
582    /// *immediate* undefined behavior, but will cause undefined behavior with most
583    /// safe operations (including dropping it).
584    ///
585    /// [`Vec<T>`]: ../../std/vec/struct.Vec.html
586    ///
587    /// # Examples
588    ///
589    /// Correct usage of this method:
590    ///
591    /// ```rust
592    /// use std::mem::MaybeUninit;
593    ///
594    /// let mut x = MaybeUninit::<bool>::uninit();
595    /// x.write(true);
596    /// let x_init = unsafe { x.assume_init() };
597    /// assert_eq!(x_init, true);
598    /// ```
599    ///
600    /// *Incorrect* usage of this method:
601    ///
602    /// ```rust,no_run
603    /// use std::mem::MaybeUninit;
604    ///
605    /// let x = MaybeUninit::<Vec<u32>>::uninit();
606    /// let x_init = unsafe { x.assume_init() };
607    /// // `x` had not been initialized yet, so this last line caused undefined behavior. ⚠️
608    /// ```
609    #[stable(feature = "maybe_uninit", since = "1.36.0")]
610    #[rustc_const_stable(feature = "const_maybe_uninit_assume_init_by_value", since = "1.59.0")]
611    #[inline(always)]
612    #[rustc_diagnostic_item = "assume_init"]
613    #[track_caller]
614    pub const unsafe fn assume_init(self) -> T {
615        // SAFETY: the caller must guarantee that `self` is initialized.
616        // This also means that `self` must be a `value` variant.
617        unsafe {
618            intrinsics::assert_inhabited::<T>();
619            // We do this via a raw ptr read instead of `ManuallyDrop::into_inner` so that there's
620            // no trace of `ManuallyDrop` in Miri's error messages here.
621            (&raw const self.value).cast::<T>().read()
622        }
623    }
624
625    /// Reads the value from the `MaybeUninit<T>` container. The resulting `T` is subject
626    /// to the usual drop handling.
627    ///
628    /// Whenever possible, it is preferable to use [`assume_init`] instead, which
629    /// prevents duplicating the content of the `MaybeUninit<T>`.
630    ///
631    /// # Safety
632    ///
633    /// It is up to the caller to guarantee that the `MaybeUninit<T>` really is in an initialized
634    /// state. Calling this when the content is not yet fully initialized causes undefined
635    /// behavior. The [type-level documentation][inv] contains more information about
636    /// this initialization invariant.
637    ///
638    /// Moreover, similar to the [`ptr::read`] function, this function creates a
639    /// bitwise copy of the contents, regardless whether the contained type
640    /// implements the [`Copy`] trait or not. When using multiple copies of the
641    /// data (by calling `assume_init_read` multiple times, or first calling
642    /// `assume_init_read` and then [`assume_init`]), it is your responsibility
643    /// to ensure that data may indeed be duplicated.
644    ///
645    /// [inv]: #initialization-invariant
646    /// [`assume_init`]: MaybeUninit::assume_init
647    ///
648    /// # Examples
649    ///
650    /// Correct usage of this method:
651    ///
652    /// ```rust
653    /// use std::mem::MaybeUninit;
654    ///
655    /// let mut x = MaybeUninit::<u32>::uninit();
656    /// x.write(13);
657    /// let x1 = unsafe { x.assume_init_read() };
658    /// // `u32` is `Copy`, so we may read multiple times.
659    /// let x2 = unsafe { x.assume_init_read() };
660    /// assert_eq!(x1, x2);
661    ///
662    /// let mut x = MaybeUninit::<Option<Vec<u32>>>::uninit();
663    /// x.write(None);
664    /// let x1 = unsafe { x.assume_init_read() };
665    /// // Duplicating a `None` value is okay, so we may read multiple times.
666    /// let x2 = unsafe { x.assume_init_read() };
667    /// assert_eq!(x1, x2);
668    /// ```
669    ///
670    /// *Incorrect* usage of this method:
671    ///
672    /// ```rust,no_run
673    /// use std::mem::MaybeUninit;
674    ///
675    /// let mut x = MaybeUninit::<Option<Vec<u32>>>::uninit();
676    /// x.write(Some(vec![0, 1, 2]));
677    /// let x1 = unsafe { x.assume_init_read() };
678    /// let x2 = unsafe { x.assume_init_read() };
679    /// // We now created two copies of the same vector, leading to a double-free ⚠️ when
680    /// // they both get dropped!
681    /// ```
682    #[stable(feature = "maybe_uninit_extra", since = "1.60.0")]
683    #[rustc_const_stable(feature = "const_maybe_uninit_assume_init_read", since = "1.75.0")]
684    #[inline(always)]
685    #[track_caller]
686    pub const unsafe fn assume_init_read(&self) -> T {
687        // SAFETY: the caller must guarantee that `self` is initialized.
688        // Reading from `self.as_ptr()` is safe since `self` should be initialized.
689        unsafe {
690            intrinsics::assert_inhabited::<T>();
691            self.as_ptr().read()
692        }
693    }
694
695    /// Drops the contained value in place.
696    ///
697    /// If you have ownership of the `MaybeUninit`, you can also use
698    /// [`assume_init`] as an alternative.
699    ///
700    /// # Safety
701    ///
702    /// It is up to the caller to guarantee that the `MaybeUninit<T>` really is
703    /// in an initialized state. Calling this when the content is not yet fully
704    /// initialized causes undefined behavior.
705    ///
706    /// On top of that, all additional invariants of the type `T` must be
707    /// satisfied, as the `Drop` implementation of `T` (or its members) may
708    /// rely on this. For example, setting a `Vec<T>` to an invalid but
709    /// non-null address makes it initialized (under the current implementation;
710    /// this does not constitute a stable guarantee), because the only
711    /// requirement the compiler knows about it is that the data pointer must be
712    /// non-null. Dropping such a `Vec<T>` however will cause undefined
713    /// behavior.
714    ///
715    /// [`assume_init`]: MaybeUninit::assume_init
716    #[stable(feature = "maybe_uninit_extra", since = "1.60.0")]
717    pub unsafe fn assume_init_drop(&mut self) {
718        // SAFETY: the caller must guarantee that `self` is initialized and
719        // satisfies all invariants of `T`.
720        // Dropping the value in place is safe if that is the case.
721        unsafe { ptr::drop_in_place(self.as_mut_ptr()) }
722    }
723
724    /// Gets a shared reference to the contained value.
725    ///
726    /// This can be useful when we want to access a `MaybeUninit` that has been
727    /// initialized but don't have ownership of the `MaybeUninit` (preventing the use
728    /// of `.assume_init()`).
729    ///
730    /// # Safety
731    ///
732    /// Calling this when the content is not yet fully initialized causes undefined
733    /// behavior: it is up to the caller to guarantee that the `MaybeUninit<T>` really
734    /// is in an initialized state.
735    ///
736    /// # Examples
737    ///
738    /// ### Correct usage of this method:
739    ///
740    /// ```rust
741    /// use std::mem::MaybeUninit;
742    ///
743    /// let mut x = MaybeUninit::<Vec<u32>>::uninit();
744    /// # let mut x_mu = x;
745    /// # let mut x = &mut x_mu;
746    /// // Initialize `x`:
747    /// x.write(vec![1, 2, 3]);
748    /// // Now that our `MaybeUninit<_>` is known to be initialized, it is okay to
749    /// // create a shared reference to it:
750    /// let x: &Vec<u32> = unsafe {
751    ///     // SAFETY: `x` has been initialized.
752    ///     x.assume_init_ref()
753    /// };
754    /// assert_eq!(x, &vec![1, 2, 3]);
755    /// # // Prevent leaks for Miri
756    /// # unsafe { MaybeUninit::assume_init_drop(&mut x_mu); }
757    /// ```
758    ///
759    /// ### *Incorrect* usages of this method:
760    ///
761    /// ```rust,no_run
762    /// use std::mem::MaybeUninit;
763    ///
764    /// let x = MaybeUninit::<Vec<u32>>::uninit();
765    /// let x_vec: &Vec<u32> = unsafe { x.assume_init_ref() };
766    /// // We have created a reference to an uninitialized vector! This is undefined behavior. ⚠️
767    /// ```
768    ///
769    /// ```rust,no_run
770    /// use std::{cell::Cell, mem::MaybeUninit};
771    ///
772    /// let b = MaybeUninit::<Cell<bool>>::uninit();
773    /// // Initialize the `MaybeUninit` using `Cell::set`:
774    /// unsafe {
775    ///     b.assume_init_ref().set(true);
776    ///    // ^^^^^^^^^^^^^^^
777    ///    // Reference to an uninitialized `Cell<bool>`: UB!
778    /// }
779    /// ```
780    #[stable(feature = "maybe_uninit_ref", since = "1.55.0")]
781    #[rustc_const_stable(feature = "const_maybe_uninit_assume_init_ref", since = "1.59.0")]
782    #[inline(always)]
783    pub const unsafe fn assume_init_ref(&self) -> &T {
784        // SAFETY: the caller must guarantee that `self` is initialized.
785        // This also means that `self` must be a `value` variant.
786        unsafe {
787            intrinsics::assert_inhabited::<T>();
788            &*self.as_ptr()
789        }
790    }
791
792    /// Gets a mutable (unique) reference to the contained value.
793    ///
794    /// This can be useful when we want to access a `MaybeUninit` that has been
795    /// initialized but don't have ownership of the `MaybeUninit` (preventing the use
796    /// of `.assume_init()`).
797    ///
798    /// # Safety
799    ///
800    /// Calling this when the content is not yet fully initialized causes undefined
801    /// behavior: it is up to the caller to guarantee that the `MaybeUninit<T>` really
802    /// is in an initialized state. For instance, `.assume_init_mut()` cannot be used to
803    /// initialize a `MaybeUninit`.
804    ///
805    /// # Examples
806    ///
807    /// ### Correct usage of this method:
808    ///
809    /// ```rust
810    /// # #![allow(unexpected_cfgs)]
811    /// use std::mem::MaybeUninit;
812    ///
813    /// # unsafe extern "C" fn initialize_buffer(buf: *mut [u8; 1024]) { unsafe { *buf = [0; 1024] } }
814    /// # #[cfg(FALSE)]
815    /// extern "C" {
816    ///     /// Initializes *all* the bytes of the input buffer.
817    ///     fn initialize_buffer(buf: *mut [u8; 1024]);
818    /// }
819    ///
820    /// let mut buf = MaybeUninit::<[u8; 1024]>::uninit();
821    ///
822    /// // Initialize `buf`:
823    /// unsafe { initialize_buffer(buf.as_mut_ptr()); }
824    /// // Now we know that `buf` has been initialized, so we could `.assume_init()` it.
825    /// // However, using `.assume_init()` may trigger a `memcpy` of the 1024 bytes.
826    /// // To assert our buffer has been initialized without copying it, we upgrade
827    /// // the `&mut MaybeUninit<[u8; 1024]>` to a `&mut [u8; 1024]`:
828    /// let buf: &mut [u8; 1024] = unsafe {
829    ///     // SAFETY: `buf` has been initialized.
830    ///     buf.assume_init_mut()
831    /// };
832    ///
833    /// // Now we can use `buf` as a normal slice:
834    /// buf.sort_unstable();
835    /// assert!(
836    ///     buf.windows(2).all(|pair| pair[0] <= pair[1]),
837    ///     "buffer is sorted",
838    /// );
839    /// ```
840    ///
841    /// ### *Incorrect* usages of this method:
842    ///
843    /// You cannot use `.assume_init_mut()` to initialize a value:
844    ///
845    /// ```rust,no_run
846    /// use std::mem::MaybeUninit;
847    ///
848    /// let mut b = MaybeUninit::<bool>::uninit();
849    /// unsafe {
850    ///     *b.assume_init_mut() = true;
851    ///     // We have created a (mutable) reference to an uninitialized `bool`!
852    ///     // This is undefined behavior. ⚠️
853    /// }
854    /// ```
855    ///
856    /// For instance, you cannot [`Read`] into an uninitialized buffer:
857    ///
858    /// [`Read`]: ../../std/io/trait.Read.html
859    ///
860    /// ```rust,no_run
861    /// use std::{io, mem::MaybeUninit};
862    ///
863    /// fn read_chunk (reader: &'_ mut dyn io::Read) -> io::Result<[u8; 64]>
864    /// {
865    ///     let mut buffer = MaybeUninit::<[u8; 64]>::uninit();
866    ///     reader.read_exact(unsafe { buffer.assume_init_mut() })?;
867    ///                             // ^^^^^^^^^^^^^^^^^^^^^^^^
868    ///                             // (mutable) reference to uninitialized memory!
869    ///                             // This is undefined behavior.
870    ///     Ok(unsafe { buffer.assume_init() })
871    /// }
872    /// ```
873    ///
874    /// Nor can you use direct field access to do field-by-field gradual initialization:
875    ///
876    /// ```rust,no_run
877    /// use std::{mem::MaybeUninit, ptr};
878    ///
879    /// struct Foo {
880    ///     a: u32,
881    ///     b: u8,
882    /// }
883    ///
884    /// let foo: Foo = unsafe {
885    ///     let mut foo = MaybeUninit::<Foo>::uninit();
886    ///     ptr::write(&mut foo.assume_init_mut().a as *mut u32, 1337);
887    ///                  // ^^^^^^^^^^^^^^^^^^^^^
888    ///                  // (mutable) reference to uninitialized memory!
889    ///                  // This is undefined behavior.
890    ///     ptr::write(&mut foo.assume_init_mut().b as *mut u8, 42);
891    ///                  // ^^^^^^^^^^^^^^^^^^^^^
892    ///                  // (mutable) reference to uninitialized memory!
893    ///                  // This is undefined behavior.
894    ///     foo.assume_init()
895    /// };
896    /// ```
897    #[stable(feature = "maybe_uninit_ref", since = "1.55.0")]
898    #[rustc_const_stable(feature = "const_maybe_uninit_assume_init", since = "1.84.0")]
899    #[inline(always)]
900    pub const unsafe fn assume_init_mut(&mut self) -> &mut T {
901        // SAFETY: the caller must guarantee that `self` is initialized.
902        // This also means that `self` must be a `value` variant.
903        unsafe {
904            intrinsics::assert_inhabited::<T>();
905            &mut *self.as_mut_ptr()
906        }
907    }
908
909    /// Extracts the values from an array of `MaybeUninit` containers.
910    ///
911    /// # Safety
912    ///
913    /// It is up to the caller to guarantee that all elements of the array are
914    /// in an initialized state.
915    ///
916    /// # Examples
917    ///
918    /// ```
919    /// #![feature(maybe_uninit_array_assume_init)]
920    /// use std::mem::MaybeUninit;
921    ///
922    /// let mut array: [MaybeUninit<i32>; 3] = [MaybeUninit::uninit(); 3];
923    /// array[0].write(0);
924    /// array[1].write(1);
925    /// array[2].write(2);
926    ///
927    /// // SAFETY: Now safe as we initialised all elements
928    /// let array = unsafe {
929    ///     MaybeUninit::array_assume_init(array)
930    /// };
931    ///
932    /// assert_eq!(array, [0, 1, 2]);
933    /// ```
934    #[unstable(feature = "maybe_uninit_array_assume_init", issue = "96097")]
935    #[inline(always)]
936    #[track_caller]
937    pub const unsafe fn array_assume_init<const N: usize>(array: [Self; N]) -> [T; N] {
938        // SAFETY:
939        // * The caller guarantees that all elements of the array are initialized
940        // * `MaybeUninit<T>` and T are guaranteed to have the same layout
941        // * `MaybeUninit` does not drop, so there are no double-frees
942        // And thus the conversion is safe
943        unsafe {
944            intrinsics::assert_inhabited::<[T; N]>();
945            intrinsics::transmute_unchecked(array)
946        }
947    }
948
949    /// Returns the contents of this `MaybeUninit` as a slice of potentially uninitialized bytes.
950    ///
951    /// Note that even if the contents of a `MaybeUninit` have been initialized, the value may still
952    /// contain padding bytes which are left uninitialized.
953    ///
954    /// # Examples
955    ///
956    /// ```
957    /// #![feature(maybe_uninit_as_bytes, maybe_uninit_slice)]
958    /// use std::mem::MaybeUninit;
959    ///
960    /// let val = 0x12345678_i32;
961    /// let uninit = MaybeUninit::new(val);
962    /// let uninit_bytes = uninit.as_bytes();
963    /// let bytes = unsafe { uninit_bytes.assume_init_ref() };
964    /// assert_eq!(bytes, val.to_ne_bytes());
965    /// ```
966    #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")]
967    pub const fn as_bytes(&self) -> &[MaybeUninit<u8>] {
968        // SAFETY: MaybeUninit<u8> is always valid, even for padding bytes
969        unsafe {
970            slice::from_raw_parts(self.as_ptr().cast::<MaybeUninit<u8>>(), super::size_of::<T>())
971        }
972    }
973
974    /// Returns the contents of this `MaybeUninit` as a mutable slice of potentially uninitialized
975    /// bytes.
976    ///
977    /// Note that even if the contents of a `MaybeUninit` have been initialized, the value may still
978    /// contain padding bytes which are left uninitialized.
979    ///
980    /// # Examples
981    ///
982    /// ```
983    /// #![feature(maybe_uninit_as_bytes)]
984    /// use std::mem::MaybeUninit;
985    ///
986    /// let val = 0x12345678_i32;
987    /// let mut uninit = MaybeUninit::new(val);
988    /// let uninit_bytes = uninit.as_bytes_mut();
989    /// if cfg!(target_endian = "little") {
990    ///     uninit_bytes[0].write(0xcd);
991    /// } else {
992    ///     uninit_bytes[3].write(0xcd);
993    /// }
994    /// let val2 = unsafe { uninit.assume_init() };
995    /// assert_eq!(val2, 0x123456cd);
996    /// ```
997    #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")]
998    pub const fn as_bytes_mut(&mut self) -> &mut [MaybeUninit<u8>] {
999        // SAFETY: MaybeUninit<u8> is always valid, even for padding bytes
1000        unsafe {
1001            slice::from_raw_parts_mut(
1002                self.as_mut_ptr().cast::<MaybeUninit<u8>>(),
1003                super::size_of::<T>(),
1004            )
1005        }
1006    }
1007
1008    /// Deprecated version of [`slice::assume_init_ref`].
1009    #[unstable(feature = "maybe_uninit_slice", issue = "63569")]
1010    #[deprecated(
1011        note = "replaced by inherent assume_init_ref method; will eventually be removed",
1012        since = "1.83.0"
1013    )]
1014    pub const unsafe fn slice_assume_init_ref(slice: &[Self]) -> &[T] {
1015        // SAFETY: Same for both methods.
1016        unsafe { slice.assume_init_ref() }
1017    }
1018
1019    /// Deprecated version of [`slice::assume_init_mut`].
1020    #[unstable(feature = "maybe_uninit_slice", issue = "63569")]
1021    #[deprecated(
1022        note = "replaced by inherent assume_init_mut method; will eventually be removed",
1023        since = "1.83.0"
1024    )]
1025    pub const unsafe fn slice_assume_init_mut(slice: &mut [Self]) -> &mut [T] {
1026        // SAFETY: Same for both methods.
1027        unsafe { slice.assume_init_mut() }
1028    }
1029
1030    /// Gets a pointer to the first element of the array.
1031    #[unstable(feature = "maybe_uninit_slice", issue = "63569")]
1032    #[inline(always)]
1033    pub const fn slice_as_ptr(this: &[MaybeUninit<T>]) -> *const T {
1034        this.as_ptr() as *const T
1035    }
1036
1037    /// Gets a mutable pointer to the first element of the array.
1038    #[unstable(feature = "maybe_uninit_slice", issue = "63569")]
1039    #[inline(always)]
1040    pub const fn slice_as_mut_ptr(this: &mut [MaybeUninit<T>]) -> *mut T {
1041        this.as_mut_ptr() as *mut T
1042    }
1043
1044    /// Deprecated version of [`slice::write_copy_of_slice`].
1045    #[unstable(feature = "maybe_uninit_write_slice", issue = "79995")]
1046    #[deprecated(
1047        note = "replaced by inherent write_copy_of_slice method; will eventually be removed",
1048        since = "1.83.0"
1049    )]
1050    pub fn copy_from_slice<'a>(this: &'a mut [MaybeUninit<T>], src: &[T]) -> &'a mut [T]
1051    where
1052        T: Copy,
1053    {
1054        this.write_copy_of_slice(src)
1055    }
1056
1057    /// Deprecated version of [`slice::write_clone_of_slice`].
1058    #[unstable(feature = "maybe_uninit_write_slice", issue = "79995")]
1059    #[deprecated(
1060        note = "replaced by inherent write_clone_of_slice method; will eventually be removed",
1061        since = "1.83.0"
1062    )]
1063    pub fn clone_from_slice<'a>(this: &'a mut [MaybeUninit<T>], src: &[T]) -> &'a mut [T]
1064    where
1065        T: Clone,
1066    {
1067        this.write_clone_of_slice(src)
1068    }
1069
1070    /// Deprecated version of [`slice::write_filled`].
1071    #[unstable(feature = "maybe_uninit_fill", issue = "117428")]
1072    #[deprecated(
1073        note = "replaced by inherent write_filled method; will eventually be removed",
1074        since = "1.83.0"
1075    )]
1076    pub fn fill<'a>(this: &'a mut [MaybeUninit<T>], value: T) -> &'a mut [T]
1077    where
1078        T: Clone,
1079    {
1080        this.write_filled(value)
1081    }
1082
1083    /// Deprecated version of [`slice::write_with`].
1084    #[unstable(feature = "maybe_uninit_fill", issue = "117428")]
1085    #[deprecated(
1086        note = "replaced by inherent write_with method; will eventually be removed",
1087        since = "1.83.0"
1088    )]
1089    pub fn fill_with<'a, F>(this: &'a mut [MaybeUninit<T>], mut f: F) -> &'a mut [T]
1090    where
1091        F: FnMut() -> T,
1092    {
1093        this.write_with(|_| f())
1094    }
1095
1096    /// Deprecated version of [`slice::write_iter`].
1097    #[unstable(feature = "maybe_uninit_fill", issue = "117428")]
1098    #[deprecated(
1099        note = "replaced by inherent write_iter method; will eventually be removed",
1100        since = "1.83.0"
1101    )]
1102    pub fn fill_from<'a, I>(
1103        this: &'a mut [MaybeUninit<T>],
1104        it: I,
1105    ) -> (&'a mut [T], &'a mut [MaybeUninit<T>])
1106    where
1107        I: IntoIterator<Item = T>,
1108    {
1109        this.write_iter(it)
1110    }
1111
1112    /// Deprecated version of [`slice::as_bytes`].
1113    #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")]
1114    #[deprecated(
1115        note = "replaced by inherent as_bytes method; will eventually be removed",
1116        since = "1.83.0"
1117    )]
1118    pub fn slice_as_bytes(this: &[MaybeUninit<T>]) -> &[MaybeUninit<u8>] {
1119        this.as_bytes()
1120    }
1121
1122    /// Deprecated version of [`slice::as_bytes_mut`].
1123    #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")]
1124    #[deprecated(
1125        note = "replaced by inherent as_bytes_mut method; will eventually be removed",
1126        since = "1.83.0"
1127    )]
1128    pub fn slice_as_bytes_mut(this: &mut [MaybeUninit<T>]) -> &mut [MaybeUninit<u8>] {
1129        this.as_bytes_mut()
1130    }
1131}
1132
1133impl<T> [MaybeUninit<T>] {
1134    /// Copies the elements from `src` to `self`,
1135    /// returning a mutable reference to the now initialized contents of `self`.
1136    ///
1137    /// If `T` does not implement `Copy`, use [`write_clone_of_slice`] instead.
1138    ///
1139    /// This is similar to [`slice::copy_from_slice`].
1140    ///
1141    /// # Panics
1142    ///
1143    /// This function will panic if the two slices have different lengths.
1144    ///
1145    /// # Examples
1146    ///
1147    /// ```
1148    /// #![feature(maybe_uninit_write_slice)]
1149    /// use std::mem::MaybeUninit;
1150    ///
1151    /// let mut dst = [MaybeUninit::uninit(); 32];
1152    /// let src = [0; 32];
1153    ///
1154    /// let init = dst.write_copy_of_slice(&src);
1155    ///
1156    /// assert_eq!(init, src);
1157    /// ```
1158    ///
1159    /// ```
1160    /// #![feature(maybe_uninit_write_slice)]
1161    ///
1162    /// let mut vec = Vec::with_capacity(32);
1163    /// let src = [0; 16];
1164    ///
1165    /// vec.spare_capacity_mut()[..src.len()].write_copy_of_slice(&src);
1166    ///
1167    /// // SAFETY: we have just copied all the elements of len into the spare capacity
1168    /// // the first src.len() elements of the vec are valid now.
1169    /// unsafe {
1170    ///     vec.set_len(src.len());
1171    /// }
1172    ///
1173    /// assert_eq!(vec, src);
1174    /// ```
1175    ///
1176    /// [`write_clone_of_slice`]: slice::write_clone_of_slice
1177    #[unstable(feature = "maybe_uninit_write_slice", issue = "79995")]
1178    pub const fn write_copy_of_slice(&mut self, src: &[T]) -> &mut [T]
1179    where
1180        T: Copy,
1181    {
1182        // SAFETY: &[T] and &[MaybeUninit<T>] have the same layout
1183        let uninit_src: &[MaybeUninit<T>] = unsafe { super::transmute(src) };
1184
1185        self.copy_from_slice(uninit_src);
1186
1187        // SAFETY: Valid elements have just been copied into `self` so it is initialized
1188        unsafe { self.assume_init_mut() }
1189    }
1190
1191    /// Clones the elements from `src` to `self`,
1192    /// returning a mutable reference to the now initialized contents of `self`.
1193    /// Any already initialized elements will not be dropped.
1194    ///
1195    /// If `T` implements `Copy`, use [`write_copy_of_slice`] instead.
1196    ///
1197    /// This is similar to [`slice::clone_from_slice`] but does not drop existing elements.
1198    ///
1199    /// # Panics
1200    ///
1201    /// This function will panic if the two slices have different lengths, or if the implementation of `Clone` panics.
1202    ///
1203    /// If there is a panic, the already cloned elements will be dropped.
1204    ///
1205    /// # Examples
1206    ///
1207    /// ```
1208    /// #![feature(maybe_uninit_write_slice)]
1209    /// use std::mem::MaybeUninit;
1210    ///
1211    /// let mut dst = [const { MaybeUninit::uninit() }; 5];
1212    /// let src = ["wibbly", "wobbly", "timey", "wimey", "stuff"].map(|s| s.to_string());
1213    ///
1214    /// let init = dst.write_clone_of_slice(&src);
1215    ///
1216    /// assert_eq!(init, src);
1217    ///
1218    /// # // Prevent leaks for Miri
1219    /// # unsafe { std::ptr::drop_in_place(init); }
1220    /// ```
1221    ///
1222    /// ```
1223    /// #![feature(maybe_uninit_write_slice)]
1224    ///
1225    /// let mut vec = Vec::with_capacity(32);
1226    /// let src = ["rust", "is", "a", "pretty", "cool", "language"].map(|s| s.to_string());
1227    ///
1228    /// vec.spare_capacity_mut()[..src.len()].write_clone_of_slice(&src);
1229    ///
1230    /// // SAFETY: we have just cloned all the elements of len into the spare capacity
1231    /// // the first src.len() elements of the vec are valid now.
1232    /// unsafe {
1233    ///     vec.set_len(src.len());
1234    /// }
1235    ///
1236    /// assert_eq!(vec, src);
1237    /// ```
1238    ///
1239    /// [`write_copy_of_slice`]: slice::write_copy_of_slice
1240    #[unstable(feature = "maybe_uninit_write_slice", issue = "79995")]
1241    pub fn write_clone_of_slice(&mut self, src: &[T]) -> &mut [T]
1242    where
1243        T: Clone,
1244    {
1245        // unlike copy_from_slice this does not call clone_from_slice on the slice
1246        // this is because `MaybeUninit<T: Clone>` does not implement Clone.
1247
1248        assert_eq!(self.len(), src.len(), "destination and source slices have different lengths");
1249
1250        // NOTE: We need to explicitly slice them to the same length
1251        // for bounds checking to be elided, and the optimizer will
1252        // generate memcpy for simple cases (for example T = u8).
1253        let len = self.len();
1254        let src = &src[..len];
1255
1256        // guard is needed b/c panic might happen during a clone
1257        let mut guard = Guard { slice: self, initialized: 0 };
1258
1259        for i in 0..len {
1260            guard.slice[i].write(src[i].clone());
1261            guard.initialized += 1;
1262        }
1263
1264        super::forget(guard);
1265
1266        // SAFETY: Valid elements have just been written into `self` so it is initialized
1267        unsafe { self.assume_init_mut() }
1268    }
1269
1270    /// Fills a slice with elements by cloning `value`, returning a mutable reference to the now
1271    /// initialized contents of the slice.
1272    /// Any previously initialized elements will not be dropped.
1273    ///
1274    /// This is similar to [`slice::fill`].
1275    ///
1276    /// # Panics
1277    ///
1278    /// This function will panic if any call to `Clone` panics.
1279    ///
1280    /// If such a panic occurs, any elements previously initialized during this operation will be
1281    /// dropped.
1282    ///
1283    /// # Examples
1284    ///
1285    /// ```
1286    /// #![feature(maybe_uninit_fill)]
1287    /// use std::mem::MaybeUninit;
1288    ///
1289    /// let mut buf = [const { MaybeUninit::uninit() }; 10];
1290    /// let initialized = buf.write_filled(1);
1291    /// assert_eq!(initialized, &mut [1; 10]);
1292    /// ```
1293    #[doc(alias = "memset")]
1294    #[unstable(feature = "maybe_uninit_fill", issue = "117428")]
1295    pub fn write_filled(&mut self, value: T) -> &mut [T]
1296    where
1297        T: Clone,
1298    {
1299        SpecFill::spec_fill(self, value);
1300        // SAFETY: Valid elements have just been filled into `self` so it is initialized
1301        unsafe { self.assume_init_mut() }
1302    }
1303
1304    /// Fills a slice with elements returned by calling a closure for each index.
1305    ///
1306    /// This method uses a closure to create new values. If you'd rather `Clone` a given value, use
1307    /// [`MaybeUninit::fill`]. If you want to use the `Default` trait to generate values, you can
1308    /// pass [`|_| Default::default()`][Default::default] as the argument.
1309    ///
1310    /// # Panics
1311    ///
1312    /// This function will panic if any call to the provided closure panics.
1313    ///
1314    /// If such a panic occurs, any elements previously initialized during this operation will be
1315    /// dropped.
1316    ///
1317    /// # Examples
1318    ///
1319    /// ```
1320    /// #![feature(maybe_uninit_fill)]
1321    /// use std::mem::MaybeUninit;
1322    ///
1323    /// let mut buf = [const { MaybeUninit::<usize>::uninit() }; 5];
1324    /// let initialized = buf.write_with(|idx| idx + 1);
1325    /// assert_eq!(initialized, &mut [1, 2, 3, 4, 5]);
1326    /// ```
1327    #[unstable(feature = "maybe_uninit_fill", issue = "117428")]
1328    pub fn write_with<F>(&mut self, mut f: F) -> &mut [T]
1329    where
1330        F: FnMut(usize) -> T,
1331    {
1332        let mut guard = Guard { slice: self, initialized: 0 };
1333
1334        for (idx, element) in guard.slice.iter_mut().enumerate() {
1335            element.write(f(idx));
1336            guard.initialized += 1;
1337        }
1338
1339        super::forget(guard);
1340
1341        // SAFETY: Valid elements have just been written into `this` so it is initialized
1342        unsafe { self.assume_init_mut() }
1343    }
1344
1345    /// Fills a slice with elements yielded by an iterator until either all elements have been
1346    /// initialized or the iterator is empty.
1347    ///
1348    /// Returns two slices. The first slice contains the initialized portion of the original slice.
1349    /// The second slice is the still-uninitialized remainder of the original slice.
1350    ///
1351    /// # Panics
1352    ///
1353    /// This function panics if the iterator's `next` function panics.
1354    ///
1355    /// If such a panic occurs, any elements previously initialized during this operation will be
1356    /// dropped.
1357    ///
1358    /// # Examples
1359    ///
1360    /// Completely filling the slice:
1361    ///
1362    /// ```
1363    /// #![feature(maybe_uninit_fill)]
1364    /// use std::mem::MaybeUninit;
1365    ///
1366    /// let mut buf = [const { MaybeUninit::uninit() }; 5];
1367    ///
1368    /// let iter = [1, 2, 3].into_iter().cycle();
1369    /// let (initialized, remainder) = buf.write_iter(iter);
1370    ///
1371    /// assert_eq!(initialized, &mut [1, 2, 3, 1, 2]);
1372    /// assert_eq!(remainder.len(), 0);
1373    /// ```
1374    ///
1375    /// Partially filling the slice:
1376    ///
1377    /// ```
1378    /// #![feature(maybe_uninit_fill)]
1379    /// use std::mem::MaybeUninit;
1380    ///
1381    /// let mut buf = [const { MaybeUninit::uninit() }; 5];
1382    /// let iter = [1, 2];
1383    /// let (initialized, remainder) = buf.write_iter(iter);
1384    ///
1385    /// assert_eq!(initialized, &mut [1, 2]);
1386    /// assert_eq!(remainder.len(), 3);
1387    /// ```
1388    ///
1389    /// Checking an iterator after filling a slice:
1390    ///
1391    /// ```
1392    /// #![feature(maybe_uninit_fill)]
1393    /// use std::mem::MaybeUninit;
1394    ///
1395    /// let mut buf = [const { MaybeUninit::uninit() }; 3];
1396    /// let mut iter = [1, 2, 3, 4, 5].into_iter();
1397    /// let (initialized, remainder) = buf.write_iter(iter.by_ref());
1398    ///
1399    /// assert_eq!(initialized, &mut [1, 2, 3]);
1400    /// assert_eq!(remainder.len(), 0);
1401    /// assert_eq!(iter.as_slice(), &[4, 5]);
1402    /// ```
1403    #[unstable(feature = "maybe_uninit_fill", issue = "117428")]
1404    pub fn write_iter<I>(&mut self, it: I) -> (&mut [T], &mut [MaybeUninit<T>])
1405    where
1406        I: IntoIterator<Item = T>,
1407    {
1408        let iter = it.into_iter();
1409        let mut guard = Guard { slice: self, initialized: 0 };
1410
1411        for (element, val) in guard.slice.iter_mut().zip(iter) {
1412            element.write(val);
1413            guard.initialized += 1;
1414        }
1415
1416        let initialized_len = guard.initialized;
1417        super::forget(guard);
1418
1419        // SAFETY: guard.initialized <= self.len()
1420        let (initted, remainder) = unsafe { self.split_at_mut_unchecked(initialized_len) };
1421
1422        // SAFETY: Valid elements have just been written into `init`, so that portion
1423        // of `this` is initialized.
1424        (unsafe { initted.assume_init_mut() }, remainder)
1425    }
1426
1427    /// Returns the contents of this `MaybeUninit` as a slice of potentially uninitialized bytes.
1428    ///
1429    /// Note that even if the contents of a `MaybeUninit` have been initialized, the value may still
1430    /// contain padding bytes which are left uninitialized.
1431    ///
1432    /// # Examples
1433    ///
1434    /// ```
1435    /// #![feature(maybe_uninit_as_bytes, maybe_uninit_write_slice, maybe_uninit_slice)]
1436    /// use std::mem::MaybeUninit;
1437    ///
1438    /// let uninit = [MaybeUninit::new(0x1234u16), MaybeUninit::new(0x5678u16)];
1439    /// let uninit_bytes = uninit.as_bytes();
1440    /// let bytes = unsafe { uninit_bytes.assume_init_ref() };
1441    /// let val1 = u16::from_ne_bytes(bytes[0..2].try_into().unwrap());
1442    /// let val2 = u16::from_ne_bytes(bytes[2..4].try_into().unwrap());
1443    /// assert_eq!(&[val1, val2], &[0x1234u16, 0x5678u16]);
1444    /// ```
1445    #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")]
1446    pub const fn as_bytes(&self) -> &[MaybeUninit<u8>] {
1447        // SAFETY: MaybeUninit<u8> is always valid, even for padding bytes
1448        unsafe {
1449            slice::from_raw_parts(self.as_ptr().cast::<MaybeUninit<u8>>(), super::size_of_val(self))
1450        }
1451    }
1452
1453    /// Returns the contents of this `MaybeUninit` slice as a mutable slice of potentially
1454    /// uninitialized bytes.
1455    ///
1456    /// Note that even if the contents of a `MaybeUninit` have been initialized, the value may still
1457    /// contain padding bytes which are left uninitialized.
1458    ///
1459    /// # Examples
1460    ///
1461    /// ```
1462    /// #![feature(maybe_uninit_as_bytes, maybe_uninit_write_slice, maybe_uninit_slice)]
1463    /// use std::mem::MaybeUninit;
1464    ///
1465    /// let mut uninit = [MaybeUninit::<u16>::uninit(), MaybeUninit::<u16>::uninit()];
1466    /// let uninit_bytes = MaybeUninit::slice_as_bytes_mut(&mut uninit);
1467    /// uninit_bytes.write_copy_of_slice(&[0x12, 0x34, 0x56, 0x78]);
1468    /// let vals = unsafe { uninit.assume_init_ref() };
1469    /// if cfg!(target_endian = "little") {
1470    ///     assert_eq!(vals, &[0x3412u16, 0x7856u16]);
1471    /// } else {
1472    ///     assert_eq!(vals, &[0x1234u16, 0x5678u16]);
1473    /// }
1474    /// ```
1475    #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")]
1476    pub const fn as_bytes_mut(&mut self) -> &mut [MaybeUninit<u8>] {
1477        // SAFETY: MaybeUninit<u8> is always valid, even for padding bytes
1478        unsafe {
1479            slice::from_raw_parts_mut(
1480                self.as_mut_ptr() as *mut MaybeUninit<u8>,
1481                super::size_of_val(self),
1482            )
1483        }
1484    }
1485
1486    /// Drops the contained values in place.
1487    ///
1488    /// # Safety
1489    ///
1490    /// It is up to the caller to guarantee that every `MaybeUninit<T>` in the slice
1491    /// really is in an initialized state. Calling this when the content is not yet
1492    /// fully initialized causes undefined behavior.
1493    ///
1494    /// On top of that, all additional invariants of the type `T` must be
1495    /// satisfied, as the `Drop` implementation of `T` (or its members) may
1496    /// rely on this. For example, setting a `Vec<T>` to an invalid but
1497    /// non-null address makes it initialized (under the current implementation;
1498    /// this does not constitute a stable guarantee), because the only
1499    /// requirement the compiler knows about it is that the data pointer must be
1500    /// non-null. Dropping such a `Vec<T>` however will cause undefined
1501    /// behaviour.
1502    #[unstable(feature = "maybe_uninit_slice", issue = "63569")]
1503    #[inline(always)]
1504    pub unsafe fn assume_init_drop(&mut self) {
1505        if !self.is_empty() {
1506            // SAFETY: the caller must guarantee that every element of `self`
1507            // is initialized and satisfies all invariants of `T`.
1508            // Dropping the value in place is safe if that is the case.
1509            unsafe { ptr::drop_in_place(self as *mut [MaybeUninit<T>] as *mut [T]) }
1510        }
1511    }
1512
1513    /// Gets a shared reference to the contained value.
1514    ///
1515    /// # Safety
1516    ///
1517    /// Calling this when the content is not yet fully initialized causes undefined
1518    /// behavior: it is up to the caller to guarantee that every `MaybeUninit<T>` in
1519    /// the slice really is in an initialized state.
1520    #[unstable(feature = "maybe_uninit_slice", issue = "63569")]
1521    #[inline(always)]
1522    pub const unsafe fn assume_init_ref(&self) -> &[T] {
1523        // SAFETY: casting `slice` to a `*const [T]` is safe since the caller guarantees that
1524        // `slice` is initialized, and `MaybeUninit` is guaranteed to have the same layout as `T`.
1525        // The pointer obtained is valid since it refers to memory owned by `slice` which is a
1526        // reference and thus guaranteed to be valid for reads.
1527        unsafe { &*(self as *const Self as *const [T]) }
1528    }
1529
1530    /// Gets a mutable (unique) reference to the contained value.
1531    ///
1532    /// # Safety
1533    ///
1534    /// Calling this when the content is not yet fully initialized causes undefined
1535    /// behavior: it is up to the caller to guarantee that every `MaybeUninit<T>` in the
1536    /// slice really is in an initialized state. For instance, `.assume_init_mut()` cannot
1537    /// be used to initialize a `MaybeUninit` slice.
1538    #[unstable(feature = "maybe_uninit_slice", issue = "63569")]
1539    #[inline(always)]
1540    pub const unsafe fn assume_init_mut(&mut self) -> &mut [T] {
1541        // SAFETY: similar to safety notes for `slice_get_ref`, but we have a
1542        // mutable reference which is also guaranteed to be valid for writes.
1543        unsafe { &mut *(self as *mut Self as *mut [T]) }
1544    }
1545}
1546
1547impl<T, const N: usize> MaybeUninit<[T; N]> {
1548    /// Transposes a `MaybeUninit<[T; N]>` into a `[MaybeUninit<T>; N]`.
1549    ///
1550    /// # Examples
1551    ///
1552    /// ```
1553    /// #![feature(maybe_uninit_uninit_array_transpose)]
1554    /// # use std::mem::MaybeUninit;
1555    ///
1556    /// let data: [MaybeUninit<u8>; 1000] = MaybeUninit::uninit().transpose();
1557    /// ```
1558    #[unstable(feature = "maybe_uninit_uninit_array_transpose", issue = "96097")]
1559    #[inline]
1560    pub const fn transpose(self) -> [MaybeUninit<T>; N] {
1561        // SAFETY: T and MaybeUninit<T> have the same layout
1562        unsafe { intrinsics::transmute_unchecked(self) }
1563    }
1564}
1565
1566impl<T, const N: usize> [MaybeUninit<T>; N] {
1567    /// Transposes a `[MaybeUninit<T>; N]` into a `MaybeUninit<[T; N]>`.
1568    ///
1569    /// # Examples
1570    ///
1571    /// ```
1572    /// #![feature(maybe_uninit_uninit_array_transpose)]
1573    /// # use std::mem::MaybeUninit;
1574    ///
1575    /// let data = [MaybeUninit::<u8>::uninit(); 1000];
1576    /// let data: MaybeUninit<[u8; 1000]> = data.transpose();
1577    /// ```
1578    #[unstable(feature = "maybe_uninit_uninit_array_transpose", issue = "96097")]
1579    #[inline]
1580    pub const fn transpose(self) -> MaybeUninit<[T; N]> {
1581        // SAFETY: T and MaybeUninit<T> have the same layout
1582        unsafe { intrinsics::transmute_unchecked(self) }
1583    }
1584}
1585
1586struct Guard<'a, T> {
1587    slice: &'a mut [MaybeUninit<T>],
1588    initialized: usize,
1589}
1590
1591impl<'a, T> Drop for Guard<'a, T> {
1592    fn drop(&mut self) {
1593        let initialized_part = &mut self.slice[..self.initialized];
1594        // SAFETY: this raw sub-slice will contain only initialized objects.
1595        unsafe {
1596            initialized_part.assume_init_drop();
1597        }
1598    }
1599}
1600
1601trait SpecFill<T> {
1602    fn spec_fill(&mut self, value: T);
1603}
1604
1605impl<T: Clone> SpecFill<T> for [MaybeUninit<T>] {
1606    default fn spec_fill(&mut self, value: T) {
1607        let mut guard = Guard { slice: self, initialized: 0 };
1608
1609        if let Some((last, elems)) = guard.slice.split_last_mut() {
1610            for el in elems {
1611                el.write(value.clone());
1612                guard.initialized += 1;
1613            }
1614
1615            last.write(value);
1616        }
1617        super::forget(guard);
1618    }
1619}
1620
1621impl<T: Copy> SpecFill<T> for [MaybeUninit<T>] {
1622    fn spec_fill(&mut self, value: T) {
1623        self.fill(MaybeUninit::new(value));
1624    }
1625}