Skip to main content

/

DocsCode

Mojo struct

UnsafeMaybeUninit

struct UnsafeMaybeUninit[T: AnyType]

A wrapper type to represent memory that may or may not be initialized.

UnsafeMaybeUninit[T] is a container for memory that may or may not be initialized. It is useful for dealing with uninitialized memory in a way that explicitly indicates to the compiler that the value inside might not be valid yet.

For types with validity invariants, using uninitialized memory can cause undefined behavior.

Important Safety Notes​

  • The destructor is a no-op: UnsafeMaybeUninit never calls the destructor of T. If the memory was initialized, you must call unsafe_assume_init_destroy() before the memory is deallocated to properly clean up the value.

  • Moving/copying behavior: When you move or copy an UnsafeMaybeUninit[T], only the raw bits are transferred. This operation does not invoke T's move constructor or copy constructor. It is a simple bitwise copy of the underlying memory. This means:

    • Moving an UnsafeMaybeUninit[T] moves the bits, not the value
    • Copying an UnsafeMaybeUninit[T] copies the bits, not the value
    • No constructors or destructors are called during these operations

  • Manual state tracking: Every method in this struct is unsafe. You must track whether the memory is initialized or uninitialized at all times. Calling a method that assumes the memory is initialized (like unsafe_assume_init_ref()) when it is not will result in undefined behavior.

  • Validity requirements: UnsafeMaybeUninit[T] has no validity requirements, any bit pattern is valid. However, once you call unsafe_assume_init_ref(), the contained value must satisfy T's validity requirements.

Parameters​

  • ​T (AnyType): The type of the element to store.

Implemented traits​

AnyType, Copyable, Defaultable, ImplicitlyDestructible, Movable

comptime members​

__copyinit__is_trivial​

comptime __copyinit__is_trivial = _is_trivially_copyable[T]()

__del__is_trivial​

comptime __del__is_trivial = True

__moveinit__is_trivial​

comptime __moveinit__is_trivial = _is_trivially_movable[T]()

Methods​

__init__​

__init__(out self)

The memory is now considered uninitialized.

__init__[MovableType: Movable](out self: UnsafeMaybeUninit[MovableType], var value: MovableType)

Create an UnsafeMaybeUninit in an initialized state.

Parameters:

  • ​MovableType (Movable): The type of the element to store.

Args:

  • ​value (MovableType): The value to initialize the memory with.

Returns:

UnsafeMaybeUninit

__copyinit__​

__copyinit__(out self, copy: Self)

Copies the raw bits from another UnsafeMaybeUninit instance.

This performs a bitwise copy of the underlying memory without invoking T's copy constructor. For UnsafeMaybeUninit[T] to be Copyable, the held value T must be trivially copyable.

Args:

  • ​copy (Self): The instance to copy from.

__moveinit__​

__moveinit__(out self, deinit take: Self)

Moves the raw bits from another UnsafeMaybeUninit instance.

This performs a bitwise move of the underlying memory without invoking T's move constructor. For UnsafeMaybeUninit[T] to be Movable, the held value T must be trivially movable.

Args:

  • ​take (Self): The value to move from.

zeroed​

static zeroed() -> Self

Create an UnsafeMaybeUninit in an uninitialized state, with the memory set to all 0 bytes.

It depends on T whether zeroed memory makes for proper initialization. For example, UnsafeMaybeUninit[Int].zeroed() is initialized, but MaybeUninit[String].zeroed() is not.

Returns:

Self: An UnsafeMaybeUninit with the memory set to all 0 bytes.

init_from​

init_from[MovableType: Movable](mut self: UnsafeMaybeUninit[MovableType], var value: MovableType)

Initialize this memory with the given value.

This overwrite any previous value without destroying it. This means, if an previous T existed in the memory, that old instance will not be destoryed potentially leading to memory leaks.

Parameters:

  • ​MovableType (Movable): The type object to move.

Args:

  • ​value (MovableType): The value to store in memory.

unsafe_assume_init_ref​

unsafe_assume_init_ref(ref self) -> ref[self_is_mut._array] T

Returns a reference to the internal value.

Calling this method assumes that the memory is initialized.

Returns:

ref: A reference to the internal value.

unsafe_assume_init_take​

unsafe_assume_init_take[U: Movable, //](mut self: UnsafeMaybeUninit[U]) -> U

Takes ownership of the internal value.

Calling this method assumes that the memory is initialized. The value is moved out of the UnsafeMaybeUninit and returned to the caller. After this call, the memory is considered uninitialized.

Parameters:

  • ​U (Movable): The element type, which must be Movable.

Returns:

U: The initialized value that was stored in this container.

unsafe_ptr​

unsafe_ptr(ref self) -> UnsafePointer[T, origin_of(self._array)]

Get a pointer to the underlying element.

Note that this method does not assumes that the memory is initialized or not. It can always be called.

Returns:

UnsafePointer: A pointer to the underlying element.

unsafe_assume_init_destroy​

unsafe_assume_init_destroy[D: ImplicitlyDestructible](mut self: UnsafeMaybeUninit[D])

Runs the destructor of the internal value.

Calling this method assumes that the memory is initialized.

Parameters:

View source

View source

Was this page helpful?

Models

Cookbook

Puzzles

Blog

Community

Contact