Errors | USearch for Mojo

Every fallible entry point raises Error and nothing else, since Mojo allows one error type per function. An Error carries a Status shared with the C interface, so a fault this binding catches before the boundary reports the status the engine would have reported for the same fault:

try:
    index.insert(keys, vectors)
except error:
    if error.status == Status.SHAPE_MISMATCH:
        pass  # the keys and the rows disagree
    print(error)  # USearch: shape-mismatch [usearch_dense_insert]

An Error keeps the engine mapped while it lives, since its name and message are the engine’s own static text. library.status_name and status_from_name spell and parse a Status through the engine’s own name table, as their twins do for scalars, residencies, traversals, moods and dense metrics:

print(library.status_name(Status.READ_ONLY), library.scalar_name(ScalarKind.BF16))  # read-only bf16

API

StructStatusWhy a call into the engine failed - the usearch_status_t vocabulary, verbatim.1

struct Status

An Error never carries SUCCESS or DEFERRED: only a Deferred reports the latter, and only until its call is final. Library.status_name spells each one as the engine does.

Fields

`code`	`Int32`	The raw `usearch_status_t` value, kept even when this build does not name it.

Values

`SUCCESS`	`Status(Int32(0))`	The call completed.
`DEFERRED`	`Status(Int32(1))`	The call was submitted deferred and is not final yet; the one non-final status.
`OUT_OF_MEMORY`	`Status(Int32(2))`	An allocation or reservation could not be satisfied.
`SHAPE_MISMATCH`	`Status(Int32(3))`	Dimensionality or row counts disagree.
`UNSUPPORTED_LAYOUT`	`Status(Int32(4))`	A stride or packing the engine cannot traverse.
`UNKNOWN_KIND`	`Status(Int32(5))`	A scalar, metric, or residency tag this build does not know.
`READ_ONLY`	`Status(Int32(6))`	A mutating verb on a handle that serves its checkpoint in place.
`IO`	`Status(Int32(7))`	A file could not be opened, read, written, or parsed.
`DEVICE`	`Status(Int32(8))`	A device could not be selected, or its memory could not be claimed.
`MALFORMED`	`Status(Int32(9))`	A caller-supplied representation could not be decoded.
`INTERNAL`	`Status(Int32(10))`	The engine reported neither success nor a failure, which names a defect rather than a state.
`OVERFLOW`	`Status(Int32(11))`	A hard design ceiling was reached, so a smaller request cannot help.
`UNINITIALIZED`	`Status(Int32(12))`	The verb needs a prior successful reservation that never happened.
`CONFIG_MISMATCH`	`Status(Int32(13))`	The request contradicts an already-frozen configuration.
`CONTENDED`	`Status(Int32(14))`	The call was refused rather than waited for, like a submission to a full deferred table.
`CANCELLED`	`Status(Int32(15))`	A progress handler stopped the operation; it published nothing.
`UNSUPPORTED`	`Status(Int32(16))`	The verb is declared for every residency but this one does not implement it.
`INVALID_ARGUMENT`	`Status(Int32(17))`	An argument breaks the verb's contract, like a required output left null.
`LIBRARY_MISSING`	`Status(Int32(-1))`	Nothing to `dlopen` - the binding's own.
`SYMBOL_MISSING`	`Status(Int32(-2))`	The library loaded but does not export a symbol the binding needs - the binding's own.
`VERSION_MISMATCH`	`Status(Int32(-3))`	The library loaded but reports a different major version than the binding's - the binding's own.

Conforms to

Copyable, Deinitable, Equatable, ImplicitlyCopyable, Movable, RegisterPassable, TrivialRegisterPassable

ofLifts a raw usearch_status_t, keeping an unnamed one rather than guessing.

def of(code: Int32) -> Self

Parameters

`codeInt32`		Whatever the C call reported, named by this build or not.

Returns

The matching status, or one carrying the unrecognized code verbatim.

StructErrorWhat went wrong inside the engine, and which entry point it was about.2

struct Error

Fields

`status`	`Status`	Which class of failure the engine reported.
`detail`	`StaticString`	The entry point it was about, for a reader rather than for a branch.
`message`	`Address`	The engine's own static message, or `NULL_ADDRESS` when it carried none.
`name`	`Address`	The engine's spelling of `status` from `usearch_status_name`, or `NULL_ADDRESS` where no engine named it.
`library`	`Optional[Library]`	The engine `message` and `name` live in, kept mapped for as long as the error is; Mojo would otherwise unload it at the last handle's last use, while the error is still being read.

Conforms to

Copyable, Deinitable, ImplicitlyCopyable, Movable, Writable

__init__A failure the binding caught before any engine could name it.

def __init__(out self, status: Status, detail: StringSpan[ImmStaticOrigin])

Parameters

`statusStatus`		Which class of failure it is.
`detailStringSpan[ImmStaticOrigin]`		The entry point or binding type it was about.

write_toWrites the status name, the entry point, and the engine's own message together.

def write_to(self, mut writer: T)

Parameters

`writerT`	mut	The sink the message is appended to.