reloco::tuple
include/reloco/tuple.hpp
reloco::tuple<Ts...> is a std::tuple<Ts...> (it derives from it) with two additions:
- Rust-like combinators:
map,zip,append,prepend,concat,first,last,for_each,apply. - reloco-style safety: reference-returning accessors cannot dangle on temporaries, and a runtime index lookup
(
visit_at) reports failure throughresult<T>instead of undefined behaviour.
Why it exists
std::tuple is only a bag of values: building a new tuple from an old one needs std::tuple_cat, std::apply and
index sequences. Writing t.map(f) or a.zip(b) says what you mean. And std::get<0>(make_tuple()) hands you an
T && into a temporary, which is easy to bind to a dangling reference; reloco::tuple returns such elements by value.
Because it derives from std::tuple, nothing you already have breaks: it converts to std::tuple implicitly, inherits
all constructors, comparisons and swap, works with std::get, std::apply, std::tuple_size and structured bindings,
and is trivially relocatable when all elements are.
Example
#include <reloco/tuple.hpp>
#include <string>
void demo() {
// Class template argument deduction works: this is reloco::tuple<int, std::string>.
reloco::tuple t(1, std::string("one"));
// get<I>() is the element access. On an lvalue it returns a reference; on an rvalue it returns the element BY VALUE
// (moved out), so `make_tuple().get<0>()` can never dangle.
t.get<0>() = 2;
int a = t.first(); // same as get<0>()
const std::string &s = t.last(); // same as get<size() - 1>()
// Structured bindings work (reloco::tuple provides std::tuple_size / std::tuple_element).
auto &[num, name] = t;
// map: apply a function to every element, collect the results in a new tuple. The function receives T& on an
// lvalue tuple, const T& on a const one, and a moved T on an rvalue (so move-only elements are fine).
auto lengths = t.map([](const auto &v) { return sizeof(v); }); // tuple<size_t, size_t>
// zip: pair elements by position. Both tuples must have the same size (compile-time check).
reloco::tuple<char, double> b('x', 2.0);
auto z = t.zip(b); // tuple<tuple<int, char>, tuple<std::string, double>>
// append / prepend / concat build longer tuples without index sequences.
auto longer = t.append(3.5); // tuple<int, std::string, double>
auto both = t.concat(reloco::tuple<char>('c')); // tuple<int, std::string, char>
// for_each runs a function per element, in order; apply calls f(elements...).
t.for_each([](auto &v) { /* inspect or mutate v */ });
int total = reloco::tuple<int, int>(1, 2).apply([](int x, int y) { return x + y; });
// visit_at: choose the element with a RUNTIME index. Every element must give the same return type (otherwise the
// result type is unnameable, which is a compile-time error). Out-of-range index -> error::out_of_bounds.
reloco::tuple<int, short, long> n(1, 2, 3);
auto r = n.visit_at(1, [](auto &v) { return static_cast<long>(v); }); // result<long>
if (!r) {
// r.error() == reloco::error::out_of_bounds
}
// Interop: into_std() moves the elements into a plain std::tuple; as_std() borrows it.
std::tuple<int, std::string> plain = std::move(t).into_std();
}
API summary
| Group | Members |
|---|---|
| Size | size(), empty() (static, constexpr) |
| Access | get<I>() (&, const &, && by value), first(), last() |
| Calling | apply(f), for_each(f), visit_at(index, f) (fallible: result<R>) |
| Transforming | map(f), zip(other), append(v), prepend(v), concat(other) |
| std interop | implicit conversion to std::tuple, as_std(), into_std() |
| Free functions | make_tuple, tie, forward_as_tuple, deduction guides (incl. from std::tuple / std::pair) |
Notes:
- Each combinator comes in
&,const &and&&flavours that decide how elements reach your function or the new tuple (reference, const reference, or moved). Theconst &&overloads are deleted. map’s function must not returnvoid(usefor_each); returning a reference gives a tuple of references, so make sure the referent outlives the result.get<I>() &&isnoexceptonly when moving the element is.- Compile-time errors:
first()/last()/visit_aton an empty tuple,zipwith different sizes,visit_atwith a function whose return type differs between elements.
Integrating with other subsystems
result<T>/error:visit_atreturnsresult<R>witherror::out_of_bounds; chain it like any other reloco fallible call.- Relocation:
is_trivially_relocatable<tuple<Ts...>>is true iff allTsare, so containers such asvectorcan relocate tuples withmemcpy. - std: pass a
reloco::tupleanywhere astd::tupleis expected, e.g.std::apply(f, t)orstd::tuple_cat.