core::mem::uninitialized - Rust
Description: API documentation for the Rust `uninitialized` fn in crate `core`.
Keywords: rust, rustlang, rust-lang, uninitialized

# Function core::mem::uninitialized 1.0.0 [−] [src]

    pub unsafe fn uninitialized<T>() -> T

Bypasses Rust's normal memory-initialization checks by pretending to produce a value of type `T`, while doing nothing at all.

This is incredibly dangerous and should not be done lightly. Deeply consider initializing your memory with a default value instead.

This is useful for FFI functions and initializing arrays sometimes, but should generally be avoided.

# Undefined behavior

It is undefined behavior to read uninitialized memory, even just an uninitialized boolean. For instance, if you branch on the value of such a boolean, your program may take one, both, or neither of the branches.

Writing to the uninitialized value is similarly dangerous. Rust believes the value is initialized, and will therefore try to `Drop` the uninitialized value and its fields if you try to overwrite it in a normal manner. The only way to safely initialize an uninitialized value is with `ptr::write`, `ptr::copy`, or `ptr::copy_nonoverlapping`.

If the value does implement `Drop`, it must be initialized before it goes out of scope (and therefore would be dropped). Note that this includes a `panic` occurring and unwinding the stack suddenly.

# Examples

Here's how to safely initialize an array of `Vec`s.

    use std::mem;
    use std::ptr;

    // Only declare the array. This safely leaves it
    // uninitialized in a way that Rust will track for us.
    // However we can't initialize it element-by-element
    // safely, and we can't use the `[value; 1000]`
    // constructor because it only works with `Copy` data.
    let mut data: [Vec<u32>; 1000];

    unsafe {
        // So we need to do this to initialize it.
        data = mem::uninitialized();

        // DANGER ZONE: if anything panics or otherwise
        // incorrectly reads the array here, we will have
        // Undefined Behavior.

        // It's ok to mutably iterate the data, since this
        // doesn't involve reading it at all.
        // (ptr and len are statically known for arrays)
        for elem in &mut data[..] {
            // *elem = Vec::new() would try to drop the
            // uninitialized memory at `elem` -- bad!
            //
            // Vec::new doesn't allocate or do really
            // anything. It's only safe to call here
            // because we know it won't panic.
            ptr::write(elem, Vec::new());
        }

        // SAFE ZONE: everything is initialized.
    }

    println!("{:?}", &data[0]);Run

This example emphasizes exactly how delicate and dangerous using `mem::uninitialized` can be. Note that the `vec!` macro does let you initialize every element with a value that is only `Clone`, so the following is semantically equivalent and vastly less dangerous, as long as you can live with an extra heap allocation:

    let data: Vec<Vec<u32>> = vec![Vec::new(); 1000];
    println!("{:?}", &data[0]);Run

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)