Unique

Module std.memory

import std.memory;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

pub final class Unique<T, A = DefaultAllocator>
    where T: Movable where A: Allocator, Defaultable, Movable

Owns zero or one movable payload and its exact allocator storage.

This noncopy owner moves without allocating. Empty construction owns no slot; successful creation owns one live T. Cleanup destroys that slot before freeing storage and before destroying the allocator. Borrowed access never retains the owner: Take, Clear, owner move and destruction invalidate every reference. External synchronization is required; payload access does not become thread safe merely because ownership is unique. No raw pointer escape is provided. T: Movable payload type, not required to be copyable or move assignable. A: Movable Defaultable concrete allocator owning the single allocation.

Example

module example.unique;
from std.memory import Unique;
fn Main() -> i32 {
    var Owner = {
        // Keep writable result storage through the explicit noncopy payload transfer.
        var OwnerCreation = Unique<i32>.TryCreate(41);
        switch OwnerCreation {
            case .Ok { Value = Value: mut Unique<i32>& } => break move(Value);
            case .Err { Error = _ } => return 1;
        }
    };
    Owner.Value().Unwrap() += 1;
    {
        let Readonly: readonly Unique<i32>& = Owner;
        if Readonly.IsEmpty || Readonly.Value().Unwrap() != 42 { return 2; }
    }
    var Moved = move(Owner);
    if !Owner.IsEmpty || Moved.Value().Unwrap() != 42 { return 3; }
    Owner = move(Moved);
    if Owner.Take().Unwrap() != 42 || !Owner.IsEmpty { return 4; }
    if Owner.Take() is .Some { Value = _ } { return 5; }
    Owner.Clear();
    return 0;
}

Unique.init

pub init()

Starts an empty owner without allocation.

Unique.init

pub init(mut AllocatorValue: A)

Starts an empty owner by transferring its allocator. AllocatorValue: Concrete allocator moved into this empty owner.

Unique.init

pub init(Source: readonly Self&) = delete;

Rejects copying unique ownership. Source: Noncopy owner.

Unique.init

pub init(Source: mut Self&&)

Transfers one allocation and its allocator without allocation. Source: Writable owner left empty and destructible.

Unique.operator

pub fn operator =(Source: readonly Self&) -> void = delete;

Rejects copying into live ownership. Source: Noncopy owner. Return: No value; deleted.

Unique.operator

pub fn operator =(Source: mut Self&&) -> void

Releases old ownership before transferring the source allocation. Source: Writable owner left empty; exact self-assignment is unchanged. Return: No value after old payload/storage cleanup and allocator replacement.

Unique.TryCreate

pub static fn TryCreate(mut Value: T) -> Result<Self, UniqueCreationError<T>>

Creates one payload with the default concrete allocator. Value: Owned payload transferred on success and returned on allocation failure. Return: Unique owner or an error retaining the uninserted payload.

Unique.TryCreate

pub static fn TryCreate(mut Value: T, mut AllocatorValue: A)
        -> Result<Self, UniqueCreationError<T>>

Creates one payload with a transferred allocator.

Only raw allocation failure is recoverable here; lifecycle traps do not roll back. The allocator transfers on either result and is cleaned up on failure. The input payload remains owned by the error if allocation fails. Value: Owned payload moved into a live slot only after allocation succeeds. AllocatorValue: Concrete allocator transferred into creation ownership. Return: Owner or allocation error retaining Value; no allocator handle is returned.

Unique.IsEmpty

pub IsEmpty: bool;

Reports whether no payload/storage is owned. Return: True for empty or moved-from owners.

Unique.Value

pub readonly fn Value() -> readonly T&?

Borrows the live payload readonly without retaining its owner. Return: Readonly reference, or none for an empty owner; invalidated by ownership changes.

Unique.Value

pub fn Value() -> mut T&?

Borrows the live payload writable without exposing a raw pointer. Return: Writable reference or none, invalidated by ownership changes.

Unique.Take

pub fn Take() -> T?

Transfers the payload out and releases its exact storage allocation. Return: Owned payload or none; this owner is empty after a successful transfer. Warning: Invalidates all outstanding payload references.

Unique.Clear

pub fn Clear() -> void

Destroys the owned payload and releases its storage, if present. Return: No value; the owner remains empty and keeps its allocator alive. Warning: Invalidates every outstanding payload reference; no allocation occurs.