# Quickstart

> UStore for C++

### Conventions

Everything lives in `unum::ustore`, and `#include <ustore/ustore.hpp>` brings in all of it.
Fallible calls return a `status_t`, a `status_code_t` beside a static message, or an `expected` that holds either a value or the `status_t` explaining its absence; both are `[[nodiscard]]`.
Dereferencing an `expected<value_type>` yields the `value_type`, and `auto [value, status]` decomposes one whose value is default constructible.
`key_from_integer` spells a non-negative integer as a key, and `key_after` answers the key right after another.
Nothing copies values out of the arena, and nothing throws.

```cpp
using namespace unum::ustore;

auto [db, status] = database_t::init_ram();
if (status.failed())
    std::fprintf(stderr, "%s\n", status.message);
```

`database_t::init_ram`, `open_ram`, `open_rocksdb`, `view_rocksdb`, `open_leveldb` and `open_nvme` wrap [the C opens](/docs/ustore/c/) of the same names, taking their argument structs as options.

`#include <ustore/db.hpp>`

`#include <ustore/ranges.hpp>`

## database_ref_t

The head of a database as a map from collection names to collections, as the calls on one executor see it, without owning either.

```cpp
class database_ref_t
```

## database_ref_t

```cpp
database_ref_t() noexcept=default;
```

```cpp
database_ref_t(receiver_t receiver) noexcept;
```

## operator ustore_database_t

The C handle of the database, so the reference passes as a `[ustore_database_t](https://www.unum.cloud/docs/ustore/c/quickstart.md#ustore_database_t)`.

```cpp
operator ustore_database_t() const noexcept;
```

## receiver

The database and executor this reference runs on, to build another reference on them.

```cpp
receiver_t receiver() const noexcept;
```

## on

The same head, running every call on `executor`.

```cpp
database_ref_t on(ustore_executor_t executor) const noexcept;
```

## deferred

The same head, whose verbs submit to `executor` and answer deferred calls.

```cpp
deferred_database_t deferred(ustore_executor_t executor) const noexcept;
```

## describe

Reports the engine of the database, what it supports and how much it holds.

```cpp
expected<ustore_database_description_t> describe() noexcept;
```

## supports_transactions

Whether the engine runs transactions.

```cpp
bool supports_transactions() noexcept;
```

## transaction

Begins a transaction, which runs its calls on this receiver's executor.

```cpp
expected<transaction_t> transaction() noexcept;
```

## snapshot

Pins a point-in-time view of the database, which the returned snapshot frees when it goes.

```cpp
expected<snapshot_t> snapshot() noexcept;
```

## operator[]

Finds the collection named `name`, or creates it when absent.

```cpp
expected<blobs_collection_t> operator[](std::string_view name) noexcept;
```

## contains

Whether a collection named `name` exists at the head.

```cpp
expected<bool> contains(std::string_view name) noexcept;
```

## collections

Lists the collections at the head, with their identifiers in `arena`.

```cpp
expected<collections_list_t> collections(arena_t & arena) noexcept;
```

## create

Creates a collection holding the modality of `collection_type_` under `name`, which no other collection may carry.

```cpp
template <typename collection_type_ = blobs_collection_t>
expected<collection_type_> create(std::string_view name) noexcept;
```

## find

The collection named `name`, refusing one that holds another modality than `collection_type_`.

```cpp
template <typename collection_type_ = blobs_collection_t>
expected<collection_type_> find(std::string_view name) noexcept;
```

Statuses: - `status_code_t::not_found_k` No collection carries `name`.
- `status_code_t::invalid_argument_k` The collection holds another modality than `collection_type_`.

## find_or_create

The collection named `name`, created when no collection carries the name.

```cpp
template <typename collection_type_ = blobs_collection_t>
expected<collection_type_> find_or_create(
    std::string_view name) noexcept;
```

## drop

Drops the collection `name` addresses, which takes the name with it.

```cpp
status_t drop(std::string_view name) noexcept;
```

## clear

Empties every collection at once, as `mode` names.

```cpp
status_t clear(ustore_drop_mode_t mode) noexcept;
```

Statuses: - `status_code_t::invalid_argument_k` The RAM and RocksDB engines refuse to drop the collections while a snapshot is open.

## compact

Reclaims the space overwritten and removed data still takes, one collection at a time, reporting its advance to `progress`, which may cancel it between collections.

```cpp
status_t compact(progress_arg_t progress = {}) noexcept;
```

## flush

Makes every commit that returned before this call durable, as if each had asked for [`ustore_durability_flushed_k`](https://www.unum.cloud/docs/ustore/c/reads-and-writes.md#ustore_durability_flushed_k).

```cpp
status_t flush() noexcept;
```

## database_t

A database as a transactional map from collection names to collections of binary values, which owns its handle.

```cpp
class database_t
```

It is thread-safe except for the opens and [`close`](#close), never copies, and outlives the collections it hands out, while its transactions and snapshots may outlive it.

## database_t

```cpp
database_t() noexcept=default;
```

```cpp
database_t(database_t const &)=delete;
```

```cpp
database_t(database_t && other) noexcept;
```

```cpp
database_t(ustore_database_t adopted) noexcept;
```

## operator=

```cpp
database_t & operator=(database_t const &)=delete;
```

```cpp
database_t & operator=(database_t && other) noexcept;
```

## close

Drops this handle, closing the database once no transaction or snapshot of it holds it open.

```cpp
void close() noexcept;
```

## ~database_t

```cpp
~database_t() noexcept;
```

## init_ram

Starts an empty database of the in-memory engine blocking on `executor`, or on the calling thread without one.

```cpp
expected<database_t> init_ram(
    ustore_database_init_ram_t options = {},
    ustore_executor_t executor = nullptr) noexcept;
```

The database runs its own calls on the calling thread until a receiver names an executor.

## open_ram

Serves the directory `options` name through the in-memory engine, which persists there as one image, blocking on `executor`, or on the calling thread without one.

```cpp
expected<database_t> open_ram(
    ustore_database_open_ram_t options,
    ustore_executor_t executor = nullptr) noexcept;
```

## open_rocksdb

Serves the directory `options` name through the RocksDB engine, blocking on `executor`, or on the calling thread without one.

```cpp
expected<database_t> open_rocksdb(
    ustore_database_open_rocksdb_t options,
    ustore_executor_t executor = nullptr) noexcept;
```

## view_rocksdb

Serves the directory `options` name through the RocksDB engine, read-only, blocking on `executor`, or on the calling thread without one.

```cpp
expected<database_t> view_rocksdb(
    ustore_database_view_rocksdb_t options,
    ustore_executor_t executor = nullptr) noexcept;
```

## open_leveldb

Serves the directory `options` name through the LevelDB engine, blocking on `executor`, or on the calling thread without one.

```cpp
expected<database_t> open_leveldb(
    ustore_database_open_leveldb_t options,
    ustore_executor_t executor = nullptr) noexcept;
```

## open_nvme

Serves the directories `options` name through the NVMe engine on the calling thread, lending it the executor they name until close.

```cpp
expected<database_t> open_nvme(
    ustore_database_open_nvme_t options) noexcept;
```

## bytes_of

The bytes `text` spells as an element of a batch, where a missing value and a null string spell empty ones.

```cpp
template <string_like_concept text_type_>
ustore_bytes_view_t bytes_of(text_type_ const & text) noexcept;
```