Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
strings.c

UTF-8 strings: the view that borrows and the string that owns.

UTF-8 strings: the view that borrows and the string that owns.Banjo carries text in two types. The view, bj_str, is a borrowed pointer and a byte count: it measures nothing, owns nothing, and is the type every reading API of the text stack takes. The owning string, bj_string, validates its bytes once, replaces every ill-formed sequence with U+FFFD, and lets everything downstream trust what it holds. This example walks the two of them in order.

#include <banjo/log.h>
#include <banjo/main.h>
#include <banjo/string.h>
int main(int argc, char* argv[]) {
(void)argc; (void)argv;
// A view can be created on a literal using BJ_STR.
// This operation doesn't allocate anything and happens at compile time.
const bj_str title = BJ_STR("Hello, UTF-8!");
bj_info("The view spans %zu bytes", title.len);
// A slice is a view that cuts another one at byte level.
const bj_str word = bj_str_slice(title, 7, 12);
bj_info("The slice at 7..12 spans %zu bytes", word.len);
// A string view operated at byte level.
// As such, two different encoding ot the same string will be
// different.
const bj_str precomposed = bj_str_from_cstr("caf\xC3\xA9");
const bj_str decomposed = bj_str_from_cstr("cafe\xCC\x81");
bj_info("The two spellings of cafe: %zu and %zu bytes, equal: %s",
precomposed.len, decomposed.len,
bj_str_eq(precomposed, decomposed) ? "yes" : "no");
// bj_string is an owning string.
// It allocats and owns content.
// Besides, it validates the UTF-8 encoding and replaces every fail with the
// standard U+FFFD code point.
// bj_string guarantees a valid UTF-8 of its content, meaning that
// downstream code can trust it on this contract.
// The view below holds a defect: E0 80 cannot sit where it is.
static const char bytes[] = "\xC3\xA9\xE0\x80\x41";
const bj_str damaged = { bytes, 5 };
bj_string* text = bj_create_string(damaged);
if (text == NULL) {
bj_err("Out of memory building the string");
return 1;
}
bj_info("The owning string, after replacement: \"%s\"", bj_string_cstr(text));
// Appending goes through the same replacement policy: the tail is
// validated too, the existing bytes untouched.
bj_append_string(text, BJ_STR(" (valid again)"));
bj_info("After appending: \"%s\"", bj_string_cstr(text));
// The hidden NUL: the string's view spans its own bytes only, and a
// NUL sits right after them, which is why cstr costs nothing.
const bj_str view = bj_string_view(text);
bj_info("The string holds %zu bytes, and cstr reads \"%s\"",
view.len, bj_string_cstr(text));
return 0;
}
#define bj_info(...)
Log a message using the BJ_LOG_INFO level.
Definition log.h:141
#define bj_err(...)
Log a message using the BJ_LOG_ERROR level.
Definition log.h:169
size_t len
Number of bytes in the view.
Definition string.h:59
#define BJ_STR(literal)
Create a view of a string literal.
Definition string.h:75
const char * bj_string_cstr(const struct bj_string *string)
Get a NUL-terminated pointer to an owning string.
bj_bool bj_str_eq(struct bj_str left, struct bj_str right)
Compare two views byte by byte.
struct bj_string * bj_create_string(struct bj_str initial)
Create an owning string from a byte view.
struct bj_str bj_string_view(const struct bj_string *string)
Get a borrowed view of an owning string.
struct bj_str bj_str_slice(struct bj_str view, size_t from, size_t to)
Create a view of a byte range within another view.
struct bj_str bj_str_from_cstr(const char *c_string)
Create a view from a NUL-terminated C string.
void bj_destroy_string(struct bj_string *string)
Destroy an owning string and release its memory.
void bj_append_string(struct bj_string *string, struct bj_str tail)
Append bytes to an owning string.
A borrowed view of a sequence of bytes.
Definition string.h:57
An owning string containing valid UTF-8.
Logging utility functions.
Portable main() replacement with platform-aware entry shim.
UTF-8 string views and owning strings.
int main(void)