# Errors

> USearch for Rust

Every fallible call returns `usearch::Result`, whose `Error` carries a `Status` and a static `message`, so nothing allocates on the failure path.
A failure the binding catches before the call crosses the boundary reports the status the engine would have used.

```rust
match index.on(&executor).search(&rows(&query, 4)?, 10, &mut arena) {
    Ok(matches) => println!("{} queries", matches.queries()),
    Err(Error { status: Status::Contended, .. }) => println!("the arena serves another call"),
    Err(error) => println!("{}: {}", error.status, error.message),
}
```

`Status` carries the C enumerators' values and leaves success to `Result`, so an `Error` never carries `Status::Deferred`, which only `Deferred::status` reports.
`Status`, `Mood`, `Residency`, `Traversal`, `DenseMetric` and `Scalar` print through `Display` and parse through `FromStr` the names the C tables own, such as `"out-of-memory"` or `"angular"`, so nothing is compared as a string.
A panic inside a predicate, progress handler or value lookup is caught at the C frame, since unwinding out of one is an abort, and resurfaces once the call is final.

`use usearch::Error;`

`use usearch::Status;`

`use usearch::*;`

## Result

The result of every fallible call in this crate.

```rust
pub type Result<Value> = Result<Value, Error>;
```

## Error

A failure, whether the engine reported it or the binding caught it before the call.

```rust
pub struct Error
```

Messages are static storage, so nothing allocates on the failure path.

- `status` `Status`: The identity of the failure, shared by every binding of the library.
- `message` `&'static str`: The detail the status alone cannot carry.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Display`, [`Error`](#Error)

## Status

Every way a call can end besides success, numbered as the library numbers them.

```rust
pub enum Status
```

An [`Error`](#Error) never carries [`Status::Deferred`](#Deferred), which only [`Deferred::status`](https://www.unum.cloud/docs/usearch/rust/executors.md#status) reports.

- `Deferred` = `1`: The call was submitted deferred and is not final yet.
- `OutOfMemory` = `2`: An allocation or reservation could not be satisfied.
- `ShapeMismatch` = `3`: Dimensionality or row counts disagree.
- `UnsupportedLayout` = `4`: A stride or packing the engine cannot traverse.
- `UnknownKind` = `5`: A scalar, metric, or residency tag this build does not know.
- `ReadOnly` = `6`: A mutating verb on a handle that serves its checkpoint in place.
- `Io` = `7`: A file could not be opened, read, written, or parsed.
- `Device` = `8`: A device could not be selected, or its memory could not be claimed.
- `Malformed` = `9`: A caller-supplied representation could not be decoded.
- `Internal` = `10`: The library reported neither success nor a failure.
- `Overflow` = `11`: A hard design ceiling was reached, like the 32-bit ID space.
- `Uninitialized` = `12`: The verb needs a prior successful reservation that never happened.
- `ConfigMismatch` = `13`: The request contradicts an already-frozen configuration.
- `Contended` = `14`: The call was refused rather than waited for, like a submission to a full deferred table.
- `Cancelled` = `15`: A progress handler stopped the call; what the finished increments leave behind is each
verb's own contract.
- `Unsupported` = `16`: The verb is declared for every residency but this one does not implement it.
- `InvalidArgument` = `17`: An argument breaks the verb's contract.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Hash`, `Display`, `FromStr`