span: Rust-style slice operations
include/reloco/span.hpp
Why
A span<T> is a non-owning view of contiguous memory, the same idea as a Rust slice (&[T] / &mut [T]).
Rust’s slice API covers the things people otherwise hand-write with index loops: splitting, searching,
rotating, partitioning. Writing those loops by hand is where off-by-one and out-of-range bugs come from.
These members give you the same vocabulary with reloco’s safety tiers.
Conventions
- Checked (
split_first,copy_from, …):RELOCO_ASSERTon misuse. try_*: returnsresult<T>witherror::out_of_bounds,container_empty,invalid_argumentornot_found.- Mutating members are
const &(a span is a view; it does not own the elements) and require a non-constT. - Reference results are
result<std::reference_wrapper<T>>(try_find,try_max, …). Results are lifetime-bound; name the result before dereferencing it (rvalue access is blocked). - Rust’s
min/max/findare spelledtry_min/try_max/try_findbecause they can fail. - Rust’s
split_at_mutandget(range)already exist assplit_atandtry_subspan.
Example 1: parsing a binary packet (split, strip, chunks)
#include <reloco/span.hpp>
// Packet layout: [magic 0xCA 0xFE][length][payload ...][checksum]
reloco::result<void> parse(reloco::span<const std::uint8_t> packet) noexcept {
constexpr std::uint8_t magic[] = {0xCA, 0xFE};
// strip_prefix() answers "does it start with this, and what is left?" in one step.
// It returns optional<span>: no match -> empty optional, nothing is copied.
auto body = packet.strip_prefix(reloco::span<const std::uint8_t>(magic));
if (!body)
return reloco::unexpected(reloco::error::invalid_argument);
// try_split_last() peels the checksum off the end. It returns a result so an empty body is an
// error value (container_empty) instead of an assertion failure.
auto parts = body->try_split_last();
if (!parts)
return reloco::unexpected(parts.error());
auto [checksum, rest] = *parts; // checksum is a reference_wrapper<const uint8_t>, rest the remaining span
// split_first() (checked variant) takes the length byte; the packet is known non-empty here.
auto [length, payload] = rest.split_first();
if (length != payload.size())
return reloco::unexpected(reloco::error::invalid_argument);
// chunks_exact(4) walks 4-byte records and skips an incomplete tail, which is exactly what a
// fixed-size record format wants. chunks_exact_remainder(4) is that skipped tail.
for (reloco::span<const std::uint8_t> record : payload.chunks_exact(4)) {
(void)record; // decode one 4-byte record
}
(void)checksum;
return {};
}
Example 2: tokenizing a buffer (split, splitn, windows)
int values[] = {3, 7, 0, 4, 0, 0, 9};
reloco::span<int> all(values);
// split(pred) yields the pieces between elements matching pred (here: zeros), lazily, as sub-spans.
// Empty pieces are kept: {3,7} {4} {} {9}.
for (reloco::span<int> run : all.split([](int v) { return v == 0; })) { /* process run */ }
// splitn(2, pred) stops after two pieces; the last piece is the untouched remainder: {3,7} {4,0,0,9}.
for (auto piece : all.splitn(2, [](int v) { return v == 0; })) {}
// rchunks(3) cuts 3-element chunks starting at the END: {0,0,9}, {7,0,4}, then the short {3} last.
for (auto chunk : all.rchunks(3)) {}
Example 3: sorted data (binary search, partition_point)
int sorted[] = {1, 3, 3, 5, 8, 13};
reloco::span<int> s(sorted);
// lower_bound/upper_bound return INDICES (like std::lower_bound minus begin()) and need sorted input.
std::size_t first_three = s.lower_bound(3); // 1: first element >= 3
std::size_t after_three = s.upper_bound(3); // 3: first element > 3
std::size_t how_many = after_three - first_three; // 2 copies of 3
// partition_point(pred) is the general form: binary search for where pred stops being true.
// Elements below 5 are the prefix, so the answer is the index of the first element >= 5.
std::size_t idx = s.partition_point([](int v) { return v < 5; }); // 3
// is_sorted() / is_sorted_by_key(key) verify a precondition before relying on it.
bool ok = s.is_sorted();
Example 4: finding things (try_find, min/max, any/all)
struct job { int priority; const char *name; };
job jobs[] = {{2, "build"}, {9, "deploy"}, {5, "test"}};
reloco::span<job> js(jobs);
// try_find_if() returns result<reference_wrapper<job>>: a reference INTO the array (not a copy), or
// error::not_found. Name the result first; hardened results cannot be dereferenced as temporaries.
auto urgent = js.try_find_if([](const job &j) { return j.priority > 8; });
if (urgent)
urgent->get().priority = 0; // mutates jobs[1]
// try_max_by_key() picks the element with the largest key (the LAST one on ties); try_min_by_key()
// returns the FIRST minimum. Empty span -> error::container_empty.
auto best = js.try_max_by_key([](const job &j) { return j.priority; });
bool any_low = js.any([](const job &j) { return j.priority < 3; });
bool all_named = js.all([](const job &j) { return j.name != nullptr; });
std::size_t high = js.count_if([](const job &j) { return j.priority >= 5; });
int total = js.fold(0, [](int acc, const job &j) { return acc + j.priority; }); // 16
Example 5: in-place rearranging (rotate, partition, copy_within, select_nth)
int data[] = {1, 2, 3, 4, 5, 6};
reloco::span<int> s(data);
s.rotate_left(2); // {3,4,5,6,1,2}: a ring buffer "unwrap" without a temporary
s.reverse(); // {2,1,6,5,4,3}
// stable_partition(pred) moves matching elements first and keeps relative order in both groups.
// It returns how many matched, so the two groups are s.subspan(0, n) and s.subspan(n).
std::size_t evens = s.stable_partition([](int v) { return v % 2 == 0; }); // {2,6,4,1,5,3}, evens == 3
// copy_within(offset, count, dest): memmove-like, overlapping ranges are safe. Shift {2,6,4} right by one.
s.copy_within(0, 3, 1);
// select_nth_unstable(n) puts the n-th smallest element in place in O(n) without a full sort.
// It returns {elements before, the element, elements after}: a cheap "median" lookup.
auto [lower, median, upper] = s.select_nth_unstable(s.size() / 2);
s.fill(0); // set every element
int next = 0;
s.fill_with([&next] { return next++; }); // generate: 0,1,2,...
Checked variants assert on bad arguments (rotate_left(7) on 6 elements); try_rotate_left(7),
try_swap_at(a, b), try_copy_from(src), try_copy_within(...) return result<void> with out_of_bounds /
invalid_argument instead.
Example 6: copying between spans
int src[] = {1, 2, 3};
int dst[] = {0, 0, 0, 0};
reloco::span<int> to(dst);
// copy_from() needs equal lengths (a silent size mismatch is a classic bug). Use a sub-span for a part.
to.subspan(0, 3).copy_from(reloco::span<const int>(src));
// try_copy_from() reports the mismatch as an error instead of asserting.
auto r = to.try_copy_from(reloco::span<const int>(src)); // fails: 4 != 3
// swap_with_span() exchanges the contents of two equally sized spans; overlaps() tells whether two
// spans share memory (useful before a copy that would be undefined for overlapping ranges).
ASCII helpers (span<char> / span<const char>)
is_ascii(), eq_ignore_ascii_case(other), make_ascii_uppercase(), make_ascii_lowercase()
work byte-wise and are locale independent.
Integration
span is already what containers hand out (as_span() style accessors), so these operations apply to any
contiguous container. Tests: tests/test_span_slice_ops.cpp.