Mutable string operations (string, sso_string, inline_string)
include/reloco/detail/string_ops_base.hpp — tests: tests/test_string_ops.cpp
Why
The three owning strings differ only in where the characters live (heap, small-buffer or fixed array). Everything
you do with text afterwards — trim it, replace parts of it, pad it, append a number, hex or base64 — is the same.
Instead of three copies, the operations live once in a CRTP base class that every mutable string inherits, so
every API below works identically on reloco::string, reloco::sso_string and reloco::inline_string<N> (and
on the wide variants, where it makes sense).
Three rules keep the code predictable:
- Read-only operations are the
string_viewones.s.split(','),s.trim(),s.rfind(...)forward tos.view(). They are documented in string-view-ops.md. Calling them on a temporary string is a compile error (the result would dangle). - In-place edits reuse the view algorithms.
trim_in_place()is “askview().trim()how much to keep, then erase the rest” — there is no second trim implementation to keep in sync. - Mutators are all-or-nothing. Every
try_*mutator returnsresult<void>(orresult<T>); when it fails (out of memory,inline_stringcapacity, bad input) the string is exactly as it was before.
Reference
| Group | Members |
|---|---|
| View forwarding (read-only) | find, rfind, find_first_of, find_first_not_of, find_last_not_of, find_if, rfind_if, contains, count, matches, match_indices, starts_with, ends_with, strip_prefix, strip_suffix, trim*, split*, rsplit*, lines, split_once, rsplit_once, split_at, try_split_at, substr, try_substr, try_parse<Int>, try_parse_bool, ASCII comparisons, is_valid_utf8, try_char_count, utf8_chars |
| Cutting | truncate(len), trim_in_place, trim_start_in_place, trim_end_in_place, trim_matches_in_place, trim_start_matches_in_place, trim_end_matches_in_place, strip_prefix_in_place, strip_suffix_in_place, retain(pred), dedup_chars() |
| Replacing / splitting off | try_replace_range(pos, count, sv), try_replace_all(from, to), try_replacen(from, to, n), try_prepend(sv), try_split_off(pos), try_drain(pos, count) |
| Case | make_ascii_uppercase, make_ascii_lowercase, make_ascii_titlecase |
| Building | try_assign_repeat(ch, n), try_append_repeat(sv, n), try_extend_from(range), try_pad_left/right(width, ch), try_center(width, ch) |
| Encoders / decoders | try_append_int<Int>(v, base, upper), try_append_hex, try_append_from_hex, try_append_base64, try_append_from_base64, try_append_url_encoded, try_append_url_decoded |
| Escaping / Display | try_append_escaped, try_append_unescaped, try_append_display<T>, try_append_debug<T> |
| Unicode | try_append_char32, try_append_utf8, try_append_utf8_lossy, try_append_utf16, try_to_utf16_into, try_utf16_length |
inline_string additionally gained try_reserve(n), which succeeds when n <= Capacity.
Notes worth knowing:
- Functions that must not alias their own text (
try_replace_all/try_replacenwith afrom/topointing into the string) returnerror::invalid_argument.try_replace_rangeandtry_prependare alias-safe. - Byte decoders (
try_append_from_hex,try_append_from_base64,try_append_url_decoded) append the decoded bytes as characters, so the string doubles as a byte buffer. - Base64 and hex are encodings, not cryptography; use a crypto library for hashes, signatures and ciphers.
- No floating point and no locale dependence anywhere.
Example 1 — cleaning user input
Config values arrive with stray whitespace and quotes. Trim in place instead of allocating a second string.
#include <reloco/string.hpp>
reloco::result<void> normalize(reloco::string &value) noexcept {
// Removes leading/trailing ASCII whitespace; computed by view().trim(), so identical to the view behavior.
if (auto r = value.trim_in_place(); !r)
return r;
// The argument is a pattern: a char, a predicate or a string. Here: strip any number of surrounding quotes.
if (auto r = value.trim_matches_in_place('"'); !r)
return r;
// `true` when the prefix was present (and has been removed); no error possible, erasing never allocates.
(void)value.strip_prefix_in_place(reloco::string_view("v="));
// Lower-case ASCII letters in place; never allocates.
value.make_ascii_lowercase();
return {};
}
Example 2 — templating with try_replace_all
#include <reloco/sso_string.hpp>
reloco::result<reloco::sso_string> greet(reloco::string_view name) noexcept {
auto text = reloco::sso_string::try_create("Hello, {name}! Bye, {name}.");
if (!text)
return text;
// from = "{name}", to = the replacement. Every occurrence is replaced in a single pass, growing the buffer once.
// On failure (allocation) the string keeps its original text. from/to must not point into `text` itself.
if (auto r = text->try_replace_all("{name}", name); !r)
return reloco::unexpected(r.error());
return text;
}
Example 3 — fixed-size formatted line without allocation
inline_string never allocates, so it suits logging in kernel or interrupt-like code. Every append reports
out_of_bounds instead of overflowing.
#include <reloco/inline_string.hpp>
reloco::result<reloco::inline_string<48>> status_line(int code, unsigned bytes) noexcept {
auto line = reloco::inline_string<48>::try_create("status=");
if (!line)
return line;
// try_append_int(value, base = 10, upper = false). Negative numbers get a '-'.
if (auto r = line->try_append_int(code); !r)
return reloco::unexpected(r.error());
if (auto r = line->try_append(" bytes=0x"); !r)
return reloco::unexpected(r.error());
// base 16 with upper-case digits.
if (auto r = line->try_append_int(bytes, 16, true); !r)
return reloco::unexpected(r.error());
// Right-pad with '.' to a fixed 40-column field so lines align.
if (auto r = line->try_pad_right(40, '.'); !r)
return reloco::unexpected(r.error());
return line;
}
Example 4 — hex / base64 / URL encoding
#include <reloco/string.hpp>
#include <reloco/span.hpp>
reloco::result<void> encode(reloco::string &out, reloco::span<const std::uint8_t> payload) noexcept {
// Lower-case hex, two digits per byte: {0xDE,0xAD} -> "dead".
if (auto r = out.try_append_hex(payload); !r)
return r;
if (auto r = out.try_append(" "); !r)
return r;
// base64(bytes, url_safe = false, padding = true). url_safe=true swaps '+/' for '-_'.
if (auto r = out.try_append_base64(payload, true, false); !r)
return r;
// Percent-encodes everything except A-Z a-z 0-9 - . _ ~ ; useful for query parameters.
return out.try_append_url_encoded("a b&c");
}
Example 5 — splitting a string in two
#include <reloco/string.hpp>
// Turns "key=value" into key (left in `line`) and value (returned), without searching twice.
reloco::result<reloco::string> take_value(reloco::string &line) noexcept {
const auto eq = line.find('=');
if (eq == reloco::string::npos)
return reloco::unexpected(reloco::error::not_found);
// Moves everything from `eq` on into a new string and truncates `line` to `eq`; same allocator as `line`.
auto tail = line.try_split_off(eq);
if (!tail)
return tail;
// Drop the "=" the tail still starts with.
(void)tail->strip_prefix_in_place('=');
return tail;
}
Example 6 — Unicode
#include <reloco/string.hpp>
#include <reloco/span.hpp>
reloco::result<void> unicode(reloco::string &s, reloco::span<const char16_t> wide) noexcept {
// A Unicode scalar value is encoded according to the string's character type: UTF-8 for `char`,
// UTF-16 for `char16_t`, UTF-32 for `char32_t`. Surrogates and values > U+10FFFF are `invalid_argument`.
if (auto r = s.try_append_char32(0x1F600); !r)
return r;
// Transcodes UTF-16 -> UTF-8 (surrogate pairs are combined; a lone surrogate is `invalid_argument`).
if (auto r = s.try_append_utf16(wide); !r)
return r;
// Untrusted bytes: keep what is valid and put U+FFFD in place of every broken sequence.
return s.try_append_utf8_lossy(reloco::string_view("ok\xFF"));
}
Example 7 — escaping and Display
#include <reloco/string.hpp>
// Builds a log line: the raw text is escaped so control characters can't break the line.
reloco::result<void> log_line(reloco::string &out, reloco::string_view raw, const MyType &value) noexcept {
// Newline -> \n, tab -> \t, quotes/backslash escaped, other control bytes -> \xNN. UTF-8 passes through.
if (auto r = out.try_append_escaped(raw); !r)
return r;
// Runs reloco::Display<MyType>::format into this string (needs a Display specialization; char strings only).
// If an append fails mid-way the string is restored and the first error returned.
return out.try_append_display(value);
}
// try_append_unescaped(text) is the inverse; unknown escapes give error::invalid_argument.
Integration notes
- Adding a new string type: inherit
detail::string_ops_base<Derived, CharT, Traits>and provideview(),data()(&),size(),try_insert,try_erase,try_resize,try_append,try_push_back,try_reserveandtry_create_like(view)(a new string of the same kind holding a copy, used bytry_split_off/try_drain). - Display / formatting:
try_append_display/try_append_debugbridgefmt.hpp’sDisplay<T>/Debug<T>to any of these strings through asink; sink writes cannot report errors, so failures are recorded and surfaced afterwards.