class bits_span_t§ Blobs
No collection exists until one is created, so every call names one.
A collection handle is cheap to construct and holds no state, and its [] operator returns a blobs_ref over one key or a batch of keys that reads and writes through the C interface:
auto [blobs, create_status] = db.create<blobs_collection_t>("blobs");
status_t status = blobs[key_from_integer(42)].assign("purpose of life");
expected<owned_value_t> value = blobs[key_from_integer(42)].value();
bool const matches = value && *value == "purpose of life";
status = blobs[{key_from_integer(43), key_from_integer(44)}].assign("same value");
expected<bool> present = blobs[key_from_integer(43)].present();
status = blobs[key_from_integer(43)].remove();
auto [arena, arena_status] = arena_t::make();
std::array<ustore_key_t, 3> keys {key_from_integer(65), key_from_integer(66), key_from_integer(67)};
expected<values_view_t> values = blobs.read(keys, arena);
for (value_view_t found : *values)
std::printf("%zu bytes\n", found.size());Read without an arena, value, present and length are shorthand: a single key answers an owned_value_t, a bool or a length, and a batch an owned<values_view_t>, an owned bits_view_t or owned lengths_view_t.
Given an arena_t&, as blobs.read(keys, arena) or blobs[keys].value(arena), .present(arena) and .length(arena) are, the same reads answer plain views into that arena. remove removes the keys, while clear_values keeps them and empties their values. keys and pairs range over a collection in key order from a start_key to an end_key, and size_range estimates how many keys it holds.
Each stream is shorthand for a range-based loop, which has no place for an arena, so it pulls pages from a cursor into one arena it owns for its lifetime.
API
Types
bits_span_tA mutable view of individual bits packed into octets.
bits_view_tA read-only view of individual bits packed into octets.
class bits_view_tstrided_spanA counted run of strided elements, writable unless element_type_ is const, like std::span.
template <typename element_type_>
class strided_spanrangeA pair of iterators, so that a move-only stream can drive a range-based loop.
template <typename iterator_type_>
class rangeplace_tOne task of a batched read or write.
struct place_tFields
collection | ustore_collection_id_t | |
|---|---|---|
key | ustore_key_t const & | |
field | std::string_view |
locations_in_collectionA batch of locations that all live in one collection the batch does not name itself.
template <typename locations_type_>
struct locations_in_collectionFields
without | location_store<locations_type_> | The locations, stored by value or by reference. |
|---|---|---|
collection | ustore_collection_id_t | Collection every location lives in. |
strided_stringsLends a strided run of string-like elements to the C ABI through a ustore_strings_view_t accessor, where a zero stride repeats the first element for every task.
template <string_like_concept element_type_>
class strided_stringsThe view it hands out points at the object itself, so the object outlives every call given the view.
lengths_view_tThe lengths a read exports into an arena beside its presence bits, where an absent value reads as missing_length_k, and a read that left its presences out reports every value present.
class lengths_view_tvalues_view_tThe values a read exports into an arena as Apache Arrow does: presence bits and the tape of values, of either offset width, where an absent value reads as a missing view.
class values_view_tstrings_cursor_tOwns a walk over the strings of one prefix from its open until its destruction, which every pull resumes past the last string the pull before it handed out, at the view its receiver read at the open.
class strings_cursor_tThe explicit form of strings_stream_t: every pull takes the caller's arena, which holds the page until its next call. The cursor copies its prefix and start, and moves but never copies itself.
blobs_range_tA slice of keys in one collection, which streams its keys through the scan of the collection's modality, and, in a blobs collection, streams its pairs and estimates its size.
class blobs_range_tClassblobs_collection_tA handle to one binary collection, cheap to construct, that reads and writes the latest state or the view of a transaction.5
class blobs_collection_tdeferred_tThe twin a deferred receiver hands out, whose verbs answer deferred calls.
using deferred_t = deferred_blobs_collection_t;clear_valuesRemoves every value and keeps the keys.
status_t clear_values() noexcept;clearRemoves every key and value and keeps the collection.
status_t clear() noexcept;dropRemoves the collection with its name and every pair it holds.
status_t drop() noexcept;atAddresses one location or a batch of them inside this collection, whose own collection wins.
blobs_ref<place_batch_t> at(
std::initializer_list<ustore_key_t> keys) noexcept;blobs_ref<place_batch_t> at(keys_view_t keys) noexcept;template <typename keys_argument_type_>
auto at(keys_argument_type_ && keys) noexcept;Addresses one location or a batch of them inside this collection, whose own collection wins.
Classblobs_read_collection_tA handle to one binary collection that only reads, cheap to construct and to copy, which addresses the latest state or the view of a transaction or snapshot.7
class blobs_read_collection_tIt holds no state of its own, so any number of threads share it, and it never outlives its database.
read_only_tThe handle a snapshot hands out for this kind of collection, which only reads.
using read_only_t = blobs_read_collection_t;deferred_tThe twin a deferred receiver hands out, whose verbs answer deferred calls.
using deferred_t = deferred_blobs_read_collection_t;modality_kWhat the collections this kind of handle addresses hold, which a creation records and a lookup checks.
ustore_modality_t modality_k;blobs_read_collection_t
blobs_read_collection_t() noexcept=default;blobs_read_collection_t(
receiver_t receiver,
ustore_collection_id_t collection) noexcept;sizeCounts the keys by streaming through all of them.
expected<std::size_t> size() const noexcept;readReads the values of a batch of keys into arena, the verb that reuses one arena call after call.
template <batch_concept keys_argument_type_>
expected<values_view_t> read(
keys_argument_type_ && keys,
arena_t & arena,
ustore_watch_t watch = ustore_watch_keys_k) noexcept;Parameters
keys | in | Keys to read, in any batch the |
|---|---|---|
arena | in | Memory the values land in, which the answer views until its next call. |
watch | in | Whether a read inside a transaction records the keys for conflicts. |
atAddresses one location or a batch of them inside this collection, whose own collection wins.
blobs_read_ref<place_batch_t> at(
std::initializer_list<ustore_key_t> keys) noexcept;blobs_read_ref<place_batch_t> at(keys_view_t keys) noexcept;template <typename keys_argument_type_>
auto at(keys_argument_type_ && keys) noexcept;Addresses one location or a batch of them inside this collection, whose own collection wins.
Classblobs_read_refA proxy that reads the values at one location or at a batch of locations, through a snapshot, a transaction or the head, and never writes them.4
template <typename locations_type_>
class blobs_read_refA read given an arena answers views into it, valid until the next call given that arena. The same read without one is shorthand: it makes a one-off arena and answers a result owning it, or a scalar copied out of it, which is slower than reusing an arena and keeps no state anywhere.
blobs_read_ref
blobs_read_ref(
receiver_t receiver,
locations_type_ && locations) noexcept;valueReads the values into arena.
expected<value_t> value(
arena_t & arena,
ustore_watch_t watch = ustore_watch_keys_k) noexcept;expected<one_off_answer_of<value_t>> value(
ustore_watch_t watch = ustore_watch_keys_k) noexcept;Reads the values into a one-off arena, which the answer owns.
lengthReads the lengths of the values into arena.
expected<length_t> length(
arena_t & arena,
ustore_watch_t watch = ustore_watch_keys_k) noexcept;expected<one_off_answer_of<length_t>> length(
ustore_watch_t watch = ustore_watch_keys_k) noexcept;Reads the lengths of the values into a one-off arena.
presentChecks which keys are present into arena, where a present value may still be empty.
expected<present_t> present(
arena_t & arena,
ustore_watch_t watch = ustore_watch_keys_k) noexcept;expected<one_off_answer_of<present_t>> present(
ustore_watch_t watch = ustore_watch_keys_k) noexcept;Checks which keys are present into a one-off arena.
Classblobs_refA proxy that reads or writes the values at one location or at a batch of locations, at the head or through a transaction.3
template <typename locations_type_>
class blobs_refOne value may go to one key or to many keys, and many values to as many keys.
assignAssigns values to the keys pairwise, or one value to every key.
template <typename values_argument_type_>
status_t assign(
values_argument_type_ && values,
ustore_durability_t durability = ustore_durability_buffered_k) noexcept;Parameters
values | in | Values to assign. |
|---|---|---|
durability | in | Whether the call returns only after the data reaches the disk. |
removeRemoves the keys together with their values.
status_t remove(
ustore_durability_t durability = ustore_durability_buffered_k) noexcept;Parameters
durability | in | Whether the call returns only after the data reaches the disk. |
|---|
clear_valuesKeeps the keys but empties their values.
status_t clear_values(
ustore_durability_t durability = ustore_durability_buffered_k) noexcept;Parameters
durability | in | Whether the call returns only after the data reaches the disk. |
|---|
Classstrided_iteratorA pointer that advances by a byte stride instead of the size of its element.5
template <typename element_type_>
class strided_iteratorA zero stride repeats one element, so every task of a batch can share a single argument.
strided_iterator
strided_iterator(
element_type_ *pointer = nullptr,
ustore_size_t stride = 0) noexcept;operator-The number of strides between two iterators, meaningful only for a stride that is a multiple of the element.
strided_iterator operator-(std::ptrdiff_t count) const noexcept;std::ptrdiff_t operator-(strided_iterator other) const noexcept;The number of strides between two iterators, meaningful only for a stride that is a multiple of the element.
repeatsWhether a zero stride repeats the same element forever.
bool repeats() const noexcept;is_continuousWhether the elements sit next to each other without gaps.
bool is_continuous() const noexcept;membersViews one member of every element with the same stride.
template <typename member_type_, typename parent_type_>
auto members(
member_type_ parent_type_::* member_pointer) const noexcept;Classstrings_collection_tA handle to one collection mapping variable-length strings onto keys, cheap to construct, which reads and writes the head or the view of a transaction.4
class strings_collection_tdeferred_tThe twin a deferred receiver hands out, whose verbs answer deferred calls.
using deferred_t = deferred_strings_collection_t;assignUpserts the key one string maps onto.
status_t assign(
value_view_t text,
ustore_key_t key,
ustore_durability_t durability = ustore_durability_buffered_k) noexcept;status_t assign(
std::span<value_view_t const> texts,
std::span<ustore_key_t const> keys,
ustore_durability_t durability = ustore_durability_buffered_k) noexcept;Upserts the keys a batch of strings map onto, one per string.
Statuses
status_code_t::invalid_argument_kThetextsandkeysdiffer in count.
clearRemoves every string, keeping the collection.
status_t clear() noexcept;dropRemoves the collection with all its strings.
status_t drop() noexcept;Classstrings_read_collection_tA handle to one collection mapping variable-length strings onto keys that only reads, cheap to construct and to copy.11
class strings_read_collection_tIt addresses either the latest state or the view of a transaction or snapshot, holds no state of its own, so any number of threads share it, and never outlives its database. Strings carry explicit lengths, so a zero byte inside one is stored like any other, and the empty string is an ordinary key.
read_only_tThe handle a snapshot hands out for this kind of collection, which only reads.
using read_only_t = strings_read_collection_t;deferred_tThe twin a deferred receiver hands out, whose verbs answer deferred calls.
using deferred_t = deferred_strings_read_collection_t;modality_kWhat the collections this kind of handle addresses hold, which a creation records and a lookup checks.
ustore_modality_t modality_k;strings_read_collection_t
strings_read_collection_t() noexcept=default;strings_read_collection_t(
receiver_t receiver,
ustore_collection_id_t collection) noexcept;readReads the keys a batch of strings map onto into arena, where a missing string reads as the nil UUID, and marks the present strings in presences when asked.
expected<keys_view_t> read(
std::span<value_view_t const> texts,
arena_t & arena,
ustore_watch_t watch = ustore_watch_keys_k,
bits_view_t *presences = nullptr) noexcept;valueReads the key text maps onto through a one-off arena, the nil UUID when the collection lacks the string.
expected<ustore_key_t> value(
value_view_t text,
ustore_watch_t watch = ustore_watch_keys_k) noexcept;presentChecks whether the collection holds text through a one-off arena.
expected<bool> present(
value_view_t text,
ustore_watch_t watch = ustore_watch_keys_k) noexcept;prefixed_pageLists up to limit strings of prefix into arena, in the order of their text.
expected<sz::strings_view_t> prefixed_page(
value_view_t prefix,
std::size_t limit,
arena_t & arena,
value_view_t start = value_view_t::make_empty(),
ustore_watch_t watch = ustore_watch_keys_k) noexcept;The page starts at start, which it returns too when the collection holds it, so a walk that pages by hand skips the string it resumed from, and prefixed streams the pages instead.
prefix_beginOpens a stream over the strings of prefix, which outlives the stream.
expected<strings_stream_t> prefix_begin(
value_view_t prefix = value_view_t::make_empty(),
std::size_t read_ahead = strings_stream_t::default_read_ahead_k) const noexcept;prefixedWalks every string of prefix, which outlives the range, in the order of their text.
expected<prefix_range_t> prefixed(
value_view_t prefix = value_view_t::make_empty(),
std::size_t read_ahead = strings_stream_t::default_read_ahead_k) const noexcept;sizeCounts the strings of prefix by streaming through all of them.
expected<std::size_t> size(
value_view_t prefix = value_view_t::make_empty()) const noexcept;Classstrings_stream_tA stream over the strings of one prefix that pulls them in pages from a cursor, in the order of their text.9
class strings_stream_tAs shorthand for a range-based loop, which has no place for an arena, it owns one arena for its lifetime, where strings_cursor_t takes the caller's per pull. The prefix it walks is borrowed, so it outlives the stream, a page short of the read-ahead ends the walk, and a default-constructed stream is the end of every walk.
default_read_ahead_kStrings one page of a walk pulls.
std::size_t default_read_ahead_k;strings_stream_t
strings_stream_t() noexcept=default;strings_stream_t(strings_stream_t &&) noexcept=default;strings_stream_t(strings_stream_t const &)=delete;operator=
strings_stream_t & operator=(strings_stream_t &&) noexcept=default;strings_stream_t & operator=(strings_stream_t const &)=delete;seekRestarts the walk at start, which is returned too when the collection holds it, through a cursor opened there.
status_t seek(value_view_t start) noexcept;seek_to_firstRestarts the walk at the first string of the prefix.
status_t seek_to_first() noexcept;operator++Advances like advance, but a failed pull ends the walk since a reference carries no status.
strings_stream_t & operator++() noexcept;strings_batchThe whole page in hand, passed strings included, which the next advance leaves behind.
sz::strings_view_t strings_batch() noexcept;operator==
bool operator==(strings_stream_t const & other) const noexcept;makeOpens a walk over the strings of prefix in collection, pulling read_ahead of them a page into an arena made where the executor of receiver computes.
expected<strings_stream_t> make(
receiver_t receiver,
ustore_collection_id_t collection,
value_view_t prefix,
std::size_t read_ahead = default_read_ahead_k) noexcept;Structplace_batch_tThe locations of a batched read or write, as the C ABI receives them.2
struct place_batch_tsame_collectionWhether every task addresses the same collection.
bool same_collection() const noexcept;*× 2The collections as the C ABI takes them.
Functions
stridedViews a contiguous container as a strided span that steps by the size of its elements.
template <std::ranges::contiguous_range container_type_>
requires std::ranges::sized_range<container_type_>
strided_span<std::remove_reference_t<std::ranges::range_reference_t<container_type_>>> strided(
container_type_ && container) noexcept;template <typename element_type_>
strided_span<element_type_> strided(
element_type_ *begin,
element_type_ *end) noexcept;Views the contiguous elements from begin up to end as a strided span.
template <typename view_type_>
requires requires(view_type_ view) { { *view.data }; { view.stride } -> std::convertible_to<ustore_size_t>; }
strided_iterator<std::remove_reference_t<decltype(*view_type_ {}.data)>> strided(
view_type_ view) noexcept;Iterates the strided run view of the C ABI describes, such as a ustore_keys_view_t, null when it has no data.
tape_ofThe tape strings pass to the C ABI as, or a zeroed view, the input's default, when they hold none.
ustore_strings_view_t tape_of(values_tape_t const & strings) noexcept;strings_ofStringZilla's view of the count strings of an output tape, of either offset width.
sz::strings_view_t strings_of(
ustore_strings_view_t const & tape,
std::size_t count) noexcept;tape_stringThe string at index of an output tape, read through the offsets its layout names.
ustore_bytes_view_t tape_string(
ustore_strings_view_t const & tape,
std::size_t index) noexcept;tape_sliceThe strings of an output tape from first on, viewing the same bytes, as a slice keeps its parent's offsets.
ustore_strings_view_t tape_slice(
ustore_strings_view_t tape,
std::size_t first) noexcept;scan_strings_pageScans one page of up to limit strings of prefix from start into arena, keeping the strings match admits and writing one BM25 score per string into scores when it is not null and the patterns carry weights.
expected<sz::strings_view_t> scan_strings_page(
receiver_t const & receiver,
ustore_watch_t watch,
ustore_collection_id_t const & collection,
value_view_t const & prefix,
value_view_t const & start,
std::size_t limit,
ustore_arena_t arena,
match_t const & match = {},
float const **scores = nullptr) noexcept;value_viewViews the bytes of a contiguous container.
template <std::ranges::contiguous_range container_type_>
requires std::ranges::sized_range<container_type_>
value_view_t value_view(container_type_ && container) noexcept;TypesMember types17
blobs_read_ref::locations_store_t | location_store<locations_type_> |
|---|---|
blobs_read_ref::locations_plain_t | typename locations_store_t::plain_t |
blobs_read_ref::keys_extractor_t | places_arg_extractor<locations_plain_t> |
blobs_read_ref::value_t | std::conditional_t<is_one_k, value_view_t, values_view_t> |
blobs_read_ref::present_t | std::conditional_t<is_one_k, bool, bits_view_t> |
blobs_read_ref::length_t | std::conditional_t<is_one_k, ustore_length_t, lengths_view_t> |
strided_iterator::element_t | element_type_ |
strided_iterator::iterator_category | std::random_access_iterator_tag |
strided_iterator::difference_type | std::ptrdiff_t |
strided_iterator::value_type | std::remove_cv_t<element_type_> |
strided_iterator::pointer | element_type_ * |
strided_iterator::reference | element_type_ & |
strings_read_collection_t::prefix_range_t | range<strings_stream_t> |
strings_stream_t::iterator_category | std::forward_iterator_tag |
strings_stream_t::difference_type | std::ptrdiff_t |
strings_stream_t::value_type | std::string_view |
place_batch_t::value_type | place_t |