string_view: Rust-style text operations
include/reloco/string_view.hpp — tests: tests/test_string_view_ops.cpp
Why
Parsing text (config lines, protocol headers, CSV, command lines) is mostly “find a separator, take what is
before it, continue with what is after it”. With std::string_view that means find + substr + index
arithmetic, and every off-by-one is a bug. reloco::string_view adds the vocabulary Rust’s str has for this:
splitting, trimming, searching, parsing integers, case-insensitive comparison and UTF-8 walking.
All of it is zero-allocation: results are views into the original text, and the split/match functions return lazy ranges you iterate with a range-for. The text must outlive the views, exactly as with any view. There is no floating point and no locale dependence anywhere.
Patterns
Most functions take a pattern, which is any of:
| Pattern | Matches |
|---|---|
a character (',') |
that character |
a predicate ([](char c) { return c == ' '; }) |
every character for which it returns true |
a string ("--", string_view, std::string) |
that exact substring (an empty string never matches) |
Conventions
- Checked members assert on misuse (
split_at);try_*members returnresult<T>witherror::out_of_bounds,not_found,invalid_argument,out_of_rangeorinteger_overflow. - Rust’s
find-style “maybe” answers areresult(split_once) ornpos(find*, as instd). - Hardened
resulttemporaries cannot be dereferenced in the same expression; bind them first (auto kv = line.split_once('='); if (kv) ...).
Example 1: parsing key = value configuration lines
#include <reloco/string_view.hpp>
// Reads a config text such as:
// # comment
// name = demo
// port = 8080
reloco::result<void> load(reloco::string_view text) noexcept {
// lines() yields each line without its "\n" or "\r\n"; no trailing empty line, nothing is copied.
for (reloco::string_view line : text.lines()) {
line = line.trim(); // trim() drops ASCII whitespace at both ends
if (line.empty() || line.starts_with('#')) // skip blanks and comments
continue;
// split_once() splits at the FIRST '='. It returns result<{first, second}> so a line without '='
// is reported as error::not_found instead of being silently misparsed.
auto kv = line.split_once('=');
if (!kv)
return reloco::unexpected(kv.error());
reloco::string_view key = kv->first.trim();
reloco::string_view value = kv->second.trim();
if (key == "port") {
// try_parse<Int>(base) parses the WHOLE view: "8080" -> 8080, "80x" -> error::invalid_argument,
// "70000" for uint16_t -> error::out_of_range (does not fit).
auto port = value.try_parse<std::uint16_t>();
if (!port)
return reloco::unexpected(port.error());
// use *port ...
}
}
return {};
}
Example 2: splitting (CSV-ish rows, paths, command lines)
reloco::string_view row = "alice,30,,Berlin";
// split(',') is lazy: each piece is a view into `row`. Empty fields are kept: "alice","30","","Berlin".
for (reloco::string_view field : row.split(',')) { /* ... */ }
// splitn(2, ' ') stops after 2 pieces; the last one is the untouched remainder.
// "GET /index.html HTTP/1.1" -> "GET", "/index.html HTTP/1.1"
for (auto part : reloco::string_view("GET /index.html HTTP/1.1").splitn(2, ' ')) {}
// rsplit_once() splits at the LAST match: handy for file extensions and "host:port".
auto ext = reloco::string_view("archive.tar.gz").rsplit_once('.'); // {"archive.tar", "gz"}
// A predicate pattern splits at any character class, here every run of digits.
for (auto word : reloco::string_view("a1b22c").split([](char c) { return c >= '0' && c <= '9'; })) {}
// split_whitespace() skips empty pieces, so repeated spaces/tabs/newlines are fine.
for (auto token : reloco::string_view(" ls -la\t/tmp ").split_whitespace()) {} // "ls" "-la" "/tmp"
// split_inclusive('\n') keeps the separator, useful when you must preserve the exact text.
for (auto line : reloco::string_view("a\nb\n").split_inclusive('\n')) {} // "a\n" "b\n"
Variants: rsplit (last to first), rsplitn, split_terminator (no trailing empty piece), split_at(pos) /
try_split_at(pos) (two halves at an index; usable with structured bindings: auto [head, tail] = s.split_at(3);).
Example 3: searching, counting, trimming
reloco::string_view s = "xx--hello--world--xx";
s.contains("hello"); // true; also contains('x') and contains(predicate)
s.count("--"); // 4: non-overlapping matches
s.rfind('-'); // index of the last '-', or string_view::npos
s.find_first_not_of("x-"); // index of the first character NOT in the set
// trim_matches() removes repeated copies of a pattern from both ends: "hello--world"
auto core = s.trim_matches('x').trim_matches("--");
// matches()/match_indices() iterate every match; indices let you point at the exact place.
for (auto [index, hit] : s.match_indices("--")) { /* index = offset of this "--" */ }
// strip_prefix/strip_suffix return optional<view>: "does it start with it, and what is left?"
if (auto rest = reloco::string_view("--verbose").strip_prefix("--"))
{ /* *rest == "verbose" */ }
Example 4: tokenizing with try_consume_int
// try_consume_int() parses an integer at the START of the view and removes it, so a loop can walk a
// "10,20,-5" style list without any index bookkeeping.
reloco::result<int> sum(reloco::string_view list) noexcept {
int total = 0;
while (!list.empty()) {
auto n = list.try_consume_int<int>(); // consumes "10", leaves ",20,-5"
if (!n)
return reloco::unexpected(n.error()); // not a number / does not fit in int
total += *n;
list.try_remove_prefix(list.starts_with(',') ? 1 : 0).value(); // skip the separator
}
return total;
}
try_parse<Int>(base) accepts bases 2..36, an optional + (and - for signed types) and never skips spaces:
trim first if the input may contain them. try_parse_bool() accepts exactly true / false.
Example 5: case-insensitive comparison (HTTP headers, keywords)
reloco::string_view header = "Content-Type: text/html";
auto [name, value] = header.split_once(':').value(); // see note on temporaries above
// ASCII-only folding: locale independent and allocation free.
if (name.eq_ignore_ascii_case("content-type")) { /* matches "CONTENT-TYPE" too */ }
if (header.starts_with_ignore_ascii_case("content-")) {}
int order = name.compare_ignore_ascii_case("Accept"); // <0, 0 or >0, usable as a sort comparator
Example 6: UTF-8 text (one-byte char only)
reloco::string_view text = "caf\xC3\xA9"; // "café": 5 bytes, 4 code points
text.is_valid_utf8(); // true; false for overlong forms, surrogates, truncated sequences
auto n = text.try_char_count(); // result 4, or error::invalid_argument when malformed
text.is_char_boundary(4); // false: byte 4 is the middle of 'é', do NOT cut the view here
// utf8_chars() yields char32_t code points; malformed bytes yield U+FFFD so the loop never gets stuck.
for (char32_t cp : text.utf8_chars()) { /* 'c' 'a' 'f' U+00E9 */ }
Example 7: operations that allocate
These are the only members that allocate; they return result<string> (or any basic_string type) and take an
optional allocator_ref first argument. Include string.hpp where they are used.
#include <reloco/string.hpp>
reloco::string_view path = "a/b/c";
// Default allocator.
auto dashed = path.try_replace("/", "-"); // result<string>: "a-b-c"
auto shout = path.try_to_ascii_uppercase(); // "A/B/C"
auto line = reloco::string_view("=").try_repeat(20); // "===================="
// Explicit allocator: pass the allocator_ref first. Failures (out of memory) are returned, never thrown.
reloco::allocator_ref heap = reloco::allocator<reloco::heap_allocator_tag>::ref();
auto copy = path.try_replace(heap, "/", "\\");
if (!copy)
return copy.error();
(Joining many views is string::try_join(range, separator).)
API summary
| Group | Members |
|---|---|
| Search | find, rfind, find_first_of, find_first_not_of, find_last_not_of, find_if, rfind_if, contains, count, matches, match_indices |
| Split | split, rsplit, splitn, rsplitn, split_terminator, split_inclusive, split_whitespace, lines, split_once, rsplit_once, split_at, try_split_at |
| Trim/strip | trim*, trim_matches, trim_start_matches, trim_end_matches, strip_prefix, strip_suffix (string or char) |
| ASCII | is_ascii, eq_ignore_ascii_case, compare_ignore_ascii_case, starts_with_ignore_ascii_case, ends_with_ignore_ascii_case, is_char_boundary |
| Parse | try_parse<Int>, try_consume_int<Int>, try_parse_bool |
| UTF-8 | is_valid_utf8, try_char_count, utf8_chars |
| Allocating | try_replace, try_to_ascii_uppercase, try_to_ascii_lowercase, try_repeat |
The owning strings (string, sso_string, inline_string) share all of these, plus in-place editing and encoders: see string-ops.md.