Container contract: lifetime, rvalue safety, and tri-tier access
Every container or view reloco ships (array, span, string/string_view,
vector, inline_vector, flat_set, basic_inline_string, …) satisfies
three orthogonal, mechanically-checkable contracts:
- Lifetime annotations (
RELOCO_OWNER/RELOCO_POINTER,RELOCO_LIFETIMEBOUND,RELOCO_LIFETIME_CAPTURE_BY_THIS/RELOCO_LIFETIME_CAPTURE_BY) — see Lifetime safety for the full macro reference. - Rvalue protection (
RELOCO_BLOCK_RVALUE_ACCESS, and explicit... const && = delete;for anything the macro does not name) so a pointer/reference/iterator can never be bound to a temporary container’s storage. - The checked/
try_*/unsafe_*tri-tier accessor convention — see Hardened containers for the user-facing rationale.
This page is the copy-paste template and checklist for applying all three to a new container or when auditing an existing one — not another explanation of why (the two guides above cover that). Read the “Tri-tier accessor template” section literally: adapt names/types, keep every attribute.
Header include list
#include "detail/assert.hpp" // RELOCO_ASSERT / RELOCO_DEBUG_ASSERT
#include "error.hpp" // reloco::error
#include "expected.hpp" // reloco::result<T>
#include "lifetime.hpp" // RELOCO_LIFETIMEBOUND / RELOCO_OWNER / RELOCO_POINTER / RELOCO_UNSAFE_BUFFER_USAGE
#include "rvalue_safety.hpp" // RELOCO_BLOCK_RVALUE_ACCESS
#include <functional> // std::reference_wrapper / std::ref / std::cref
Wrap the raw pointer-arithmetic implementation of the container’s
namespace reloco body in
RELOCO_BEGIN_UNSAFE_BUFFER_USAGE/RELOCO_END_UNSAFE_BUFFER_USAGE (see
array.hpp, span.hpp, string.hpp, vector.hpp); this is orthogonal to
the per-accessor RELOCO_UNSAFE_BUFFER_USAGE attribute below.
Class declaration template
// Owning container (embeds or allocates its own storage):
template <typename T> class RELOCO_OWNER my_container {
public:
using value_type = T;
using size_type = std::size_t;
using difference_type = std::ptrdiff_t;
using reference = T &;
using const_reference = const T &;
using pointer = T *;
using const_pointer = const T *;
using iterator = T *;
using const_iterator = const T *;
using reverse_iterator = std::reverse_iterator<iterator>;
using const_reverse_iterator = std::reverse_iterator<const_iterator>;
// First line in `public:` for every container/view — see below.
RELOCO_BLOCK_RVALUE_ACCESS(T);
// ...
};
// Non-owning view/reference wrapper (borrows external storage):
template <typename T> class RELOCO_POINTER my_view {
// Same member-type aliases and RELOCO_BLOCK_RVALUE_ACCESS(T) as above.
};
Use RELOCO_OWNER when the type manages the lifetime of its storage
(array, vector, inline_vector, basic_string, basic_inline_string,
flat_set).
Use RELOCO_POINTER when the type is a non-owning handle over storage it
does not manage (span, function_ref, mutable_container_ref,
stack_allocator_context).
Tri-tier accessor template
Copy this block verbatim for any indexable/dereferenceable container backed
by a contiguous T *data_ + size_type size_; rename data_/size_ and
swap the bounds check as needed (e.g. non-empty vs. in-range).
// ---- checked tier: RELOCO_ASSERT, active even when NDEBUG is defined ----
[[nodiscard]] T &operator[](size_type index) & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_ASSERT(index < size_, "my_container index out of bounds");
return data_[index];
}
[[nodiscard]] const T &operator[](size_type index) const & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_ASSERT(index < size_, "my_container index out of bounds");
return data_[index];
}
[[nodiscard]] T &front() & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_ASSERT(!empty(), "my_container is empty");
return data_[0];
}
[[nodiscard]] const T &front() const & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_ASSERT(!empty(), "my_container is empty");
return data_[0];
}
[[nodiscard]] T &back() & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_ASSERT(!empty(), "my_container is empty");
return data_[size_ - 1];
}
[[nodiscard]] const T &back() const & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_ASSERT(!empty(), "my_container is empty");
return data_[size_ - 1];
}
// `data()` asserts non-empty; it is the checked tier's raw-pointer
// accessor and returns a (pointer, size()) pair, never an unbounded,
// null-terminated pointer (that is `unsafe_c_str()`/`c_str()`-style
// access below, always unsafe-tier only).
[[nodiscard]] T *data() & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_ASSERT(!empty(), "my_container is empty");
return data_;
}
[[nodiscard]] const T *data() const & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_ASSERT(!empty(), "my_container is empty");
return data_;
}
// ---- fallible tier: reloco::result instead of trapping ----
[[nodiscard]] result<std::reference_wrapper<T>> try_at(size_type index) & noexcept RELOCO_LIFETIMEBOUND {
if (index >= size_)
return unexpected(error::out_of_bounds);
return std::ref(data_[index]);
}
[[nodiscard]] result<std::reference_wrapper<const T>> try_at(size_type index) const & noexcept
RELOCO_LIFETIMEBOUND {
if (index >= size_)
return unexpected(error::out_of_bounds);
return std::cref(data_[index]);
}
[[nodiscard]] result<std::reference_wrapper<T>> try_front() & noexcept RELOCO_LIFETIMEBOUND {
if (empty())
return unexpected(error::container_empty);
return std::ref(data_[0]);
}
[[nodiscard]] result<std::reference_wrapper<const T>> try_front() const & noexcept RELOCO_LIFETIMEBOUND {
if (empty())
return unexpected(error::container_empty);
return std::cref(data_[0]);
}
[[nodiscard]] result<T *> try_data() & noexcept RELOCO_LIFETIMEBOUND {
if (empty())
return unexpected(error::container_empty);
return data_;
}
[[nodiscard]] result<const T *> try_data() const & noexcept RELOCO_LIFETIMEBOUND {
if (empty())
return unexpected(error::container_empty);
return data_;
}
// ---- explicitly-unsafe tier: RELOCO_UNSAFE_BUFFER_USAGE, RELOCO_DEBUG_ASSERT only ----
[[nodiscard]] RELOCO_UNSAFE_BUFFER_USAGE T &unsafe_at(size_type index) & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_DEBUG_ASSERT(index < size_, "my_container index out of bounds");
return data_[index];
}
[[nodiscard]] RELOCO_UNSAFE_BUFFER_USAGE const T &unsafe_at(size_type index) const & noexcept
RELOCO_LIFETIMEBOUND {
RELOCO_DEBUG_ASSERT(index < size_, "my_container index out of bounds");
return data_[index];
}
[[nodiscard]] RELOCO_UNSAFE_BUFFER_USAGE T *unsafe_data() & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_DEBUG_ASSERT(!empty(), "my_container has no data");
return data_;
}
[[nodiscard]] RELOCO_UNSAFE_BUFFER_USAGE const T *unsafe_data() const & noexcept RELOCO_LIFETIMEBOUND {
RELOCO_DEBUG_ASSERT(!empty(), "my_container has no data");
return data_;
}
// ---- iteration: same RELOCO_LIFETIMEBOUND rule applies uniformly ----
[[nodiscard]] iterator begin() & noexcept RELOCO_LIFETIMEBOUND { return data_; }
[[nodiscard]] iterator end() & noexcept RELOCO_LIFETIMEBOUND { return data_ + size_; }
[[nodiscard]] const_iterator begin() const & noexcept RELOCO_LIFETIMEBOUND { return data_; }
[[nodiscard]] const_iterator end() const & noexcept RELOCO_LIFETIMEBOUND { return data_ + size_; }
[[nodiscard]] const_iterator cbegin() const & noexcept RELOCO_LIFETIMEBOUND { return data_; }
[[nodiscard]] const_iterator cend() const & noexcept RELOCO_LIFETIMEBOUND { return data_ + size_; }
Rules baked into every line above, and non-negotiable for a new container:
- Every accessor that hands back a reference, pointer, or iterator into the
container’s own storage carries
RELOCO_LIFETIMEBOUND— in all three tiers alike (checked,try_*,unsafe_*), not justdata()/begin()/end(). This applies uniformly to plain reference-returning accessors (operator[]/front()/back()/unsafe_at()) too, not only to pointer/iterator ones;array.hpp,span.hpp,vector.hpp,basic_inline_string,flat_set, andcollection_view/mutable_collection_viewall follow this uniformly. - A raw, unbounded, null-terminated pointer accessor (
c_str()-style) is never part of the checked tier. Name itunsafe_c_str()(seestring.hpp/inline_string.hpp) and gate it the same way asunsafe_data()above; there is no checked ortry_*counterpart because there is no safe bounded alternative to it. try_*accessors that return a borrow useresult<std::reference_wrapper<T>>(neverresult<T &>— references are not assignable, soexpectedcannot store one directly) or a raw pointer fortry_data(); both still needRELOCO_LIFETIMEBOUND.unsafe_*accessors useRELOCO_DEBUG_ASSERT, neverRELOCO_ASSERT— the entire point of the unsafe tier is that the precondition is the caller’s responsibility in release builds.
Rvalue protection template
public:
RELOCO_BLOCK_RVALUE_ACCESS(T); // first line after `public:`
RELOCO_BLOCK_RVALUE_ACCESS(Type) (see rvalue_safety.hpp) deletes the
&&-qualified overload of every accessor named above
(operator[], front/back, at/try_at/unsafe_at,
data/try_data/unsafe_data, begin/end/rbegin/rend/c*,
operator*/operator->/get/unsafe_get) in one line, so a caller cannot
do my_container{...}.data() and keep the pointer past the full expression.
Any accessor the shared macro does not name — because it is specific to one
container (view(), as_span(), unsafe_c_str(), a bespoke
try_substr()) — still needs its own explicit deletion if it can return a
borrow:
[[nodiscard]] view_type view() const & noexcept RELOCO_LIFETIMEBOUND { return view_type(data_, size_); }
view_type view() const && = delete;
[[nodiscard]] RELOCO_UNSAFE_BUFFER_USAGE const_pointer unsafe_c_str() const & noexcept RELOCO_LIFETIMEBOUND {
return data_;
}
const_pointer unsafe_c_str() const && = delete;
Move-only owning containers (vector, basic_string) get this “for free”
in the sense that there is no copy constructor to produce a throwaway
prvalue in the first place, but the macro still matters for the common
try_create(...).value()... chaining mistake, since the result<T>
temporary’s .value() returns an rvalue reference to the container.
Constructors/setters that capture a borrow
Anything that stores a caller-supplied pointer/reference inside the
object (type-erased handles like function_ref, mutable_container_ref,
stack_allocator_context — as opposed to a container copying/owning the
value) needs RELOCO_LIFETIME_CAPTURE_BY_THIS on the captured parameter, in
addition to (or, per the equivalence noted in
Lifetime safety, instead of on a
void-returning setter) RELOCO_LIFETIMEBOUND:
template <typename Container, std::enable_if_t<is_container_ref_source<Container, T>::value, int> = 0>
constexpr explicit my_view(Container &c RELOCO_LIFETIMEBOUND RELOCO_LIFETIME_CAPTURE_BY_THIS) noexcept
: ctx_(std::addressof(c)) {}
Move-only/use-after-move wrappers
If the type has a hazardous “used after move” or “used after take/reset”
state (checked_value, optional, inplace_function), add the
consumed-state annotations from lifetime.hpp so Clang’s -Wconsumed
tracks it: RELOCO_CONSUMABLE(unconsumed) on the class,
RELOCO_RETURN_TYPESTATE(unconsumed)/RELOCO_RETURN_TYPESTATE(consumed) on
constructors/reset(), RELOCO_CALLABLE_WHEN("unconsumed") on every
accessor that traps on a moved-from/empty object, and
RELOCO_SET_TYPESTATE(consumed) on take()/reset(). See
checked_value.hpp’s as_known() for the RELOCO_RETURN_TYPESTATE-only
&-qualified escape hatch used at reference/pointer boundaries where Clang
would otherwise infer "unknown".
Checklist
- Class tagged
RELOCO_OWNER(owns storage) orRELOCO_POINTER(non-owning view/handle). RELOCO_BLOCK_RVALUE_ACCESS(ElementType)is the first line afterpublic:.- Every reference/pointer/iterator-returning accessor, in all three
tiers, carries
RELOCO_LIFETIMEBOUND. - Every borrow-returning accessor not named by the shared macro has its
own explicit
... const && = delete;(or non-const &&, as applicable). - Any unbounded/null-terminated raw-pointer accessor is
unsafe_*-only, with no checked ortry_*counterpart. - Constructors/setters that capture a borrow into the object use
RELOCO_LIFETIME_CAPTURE_BY_THIS/RELOCO_LIFETIME_CAPTURE_BY(...). unsafe_*accessors useRELOCO_DEBUG_ASSERT, neverRELOCO_ASSERT, and areRELOCO_UNSAFE_BUFFER_USAGE-gated.- Move-only/use-after-move wrappers carry the
-Wconsumedtypestate annotations. - Validate with
./scripts/check-unsafe-buffer-usage.sh(0 diagnostics across C++17/20/23) and aclang++-24build/test run — annotation correctness only shows up as Clang diagnostics, never as a GCC error.