# Errors

> UStore for Rust

Every fallible call answers `Result<T, Error>`, where the error carries the `Status` the C ABI reported and the static message beside it, 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.
`Status` carries the C enumerators' values and leaves success to `Result`, so an `Error` never carries `Status::Deferred`, which only `Deferred::status` reports, and a status a newer library added reads as `Status::Internal`.
`Status`, `Mood`, `Durability`, `Watch`, `DropMode`, `Isolation`, `Transport`, `Engine`, `Modality`, `Role` and `Modification` print through `Display` and parse through `FromStr` the spellings the C tables own, such as `"not-found"` or `"strict-serializable"`, so nothing is compared as a string.
`ustore::version()` names the library the program runs against, such as `"1.0.0"`.

```rust
match database.head().collection_find("nowhere", &mut arena) {
    Err(failure) if failure.status == ustore::Status::NotFound => println!("{}: {failure}", failure.status),
    other => { other?; }
}
```

`use ustore::Error;`

`use ustore::Status;`

`use ustore::*;`

## Result

The result of every fallible call in this crate.

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

## Error

A failure the library reported, or the binding caught before the call, with a static message so nothing allocates on the failure path.

```rust
pub struct Error
```

- `status` `Status`: The identity of the failure, shared with the C ABI.
- `message` `&'static str`: The detail the status alone cannot carry.

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

## Status

What went wrong, in the vocabulary of `ustore_status_t`, whose success is left to [`Result`](#Result).

```rust
pub enum Status
```

An [`Error`](#Error) never carries [`Status::Deferred`](#Deferred), which only [`Deferred::status`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#status) reports.

- `Deferred` = `1`: A deferred call that has not finished; the one status that is never final.
- `OutOfMemory` = `2`: An allocation could not be satisfied.
- `ReadOnly` = `6`: The call would change a database opened read-only, as [`Database::view_rocksdb`](https://www.unum.cloud/docs/ustore/rust/quickstart.md#view_rocksdb) opens one.
- `Io` = `7`: A file or directory could not be opened, read, written, or closed.
- `Device` = `8`: A device could not be selected, or its memory could not be claimed.
- `Malformed` = `9`: Stored or supplied data could not be decoded.
- `Internal` = `10`: The engine failed in a way no other status names.
- `Uninitialized` = `12`: The call needs a database or transaction that was never opened.
- `Contended` = `14`: The call was refused rather than waited for.
- `Cancelled` = `15`: A progress callback stopped the call, which published nothing.
- `Unsupported` = `16`: The engine or build does not implement what the call asks for.
- `InvalidArgument` = `17`: An argument is null, contradicts another one, or carries unaccepted options.
- `NotFound` = `18`: A snapshot, collection, or document the call addresses does not exist.
- `AlreadyExists` = `19`: A snapshot, collection, or document the call creates already exists.
- `WriteConflict` = `20`: A concurrent writer changed a key this transaction wrote.
- `ReadConflict` = `21`: A concurrent writer changed a key this transaction read.
- `PhantomConflict` = `22`: A concurrent writer inserted into a range this transaction scanned.
- `CapacityExhausted` = `23`: A hard design ceiling was reached.

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