Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
utf8_decode.c
Go to the documentation of this file.
1
14
15#include <banjo/log.h>
16#include <banjo/main.h>
17#include <banjo/string.h>
18#include <banjo/unicode.h>
19
20// A callback for bj_utf8_scan: prints one line per character attempt,
21// then keeps scanning. The report says what the bytes are; this decides
22// what they become on screen.
23static bj_bool print_report(const struct bj_utf8_report* report, void* user_data) {
24 (void)user_data;
25 const int valid = (report->state == BJ_UTF8_STATE_VALID);
26 bj_info(" %3zu..%3zu %s U+%04X", report->byte_offset,
27 report->byte_offset + report->n_bytes,
28 valid ? "valid " : "replaced ",
29 valid ? report->value : 0xFFFDu);
30 return BJ_TRUE;
31}
32
33int main(int argc, char* argv[]) {
34 (void)argc; (void)argv;
35
36 // The pull door: one character per call, the cursor walking the view.
37 const bj_str text = bj_str_from_cstr("Hello, UTF-8!");
38 struct bj_utf8_report report;
39 size_t cursor = 0;
40 size_t count = 0;
41
42 while (bj_utf8_next(text, &cursor, &report)) {
43 ++count;
44 }
45 bj_info("The pull door read %zu characters", count);
46
47 // The push door: the same reports, handed to a callback over the
48 // whole view. Protocols and diagnostics read this way.
49 bj_info("The push door, same view:");
50 const size_t report_count = bj_utf8_scan(text, print_report, NULL);
51 bj_info(" %zu reports", report_count);
52
53 // A view with a defect: E9 decodes, then E0 80 cannot sit where it
54 // is. Each failed report covers the plausible prefix without the
55 // byte that broke it, and the A after the garbage comes out whole.
56 static const char bytes[] = "\xC3\xA9\xE0\x80\x41";
57 const bj_str damaged = { bytes, 5 };
58 bj_info("A damaged view, E9 then E0 80 41:");
59 bj_utf8_scan(damaged, print_report, NULL);
60
61 // Validation answers before anything is built: the door protocols
62 // and editors use. first_error names the byte where the failure
63 // starts.
64 size_t first_error = 0;
65 if (!bj_utf8_validate(damaged, &first_error)) {
66 bj_info("The view is not valid UTF-8: first error at byte %zu",
67 first_error);
68 }
69
70 // Writing a character back: the shortest form, and nothing at all
71 // for a value with no spelling, as a surrogate.
72 char encoded[4];
73 const size_t written_e9 = bj_utf8_encode(0xE9, encoded);
74 const size_t written_surrogate = bj_utf8_encode(0xD800, encoded);
75 bj_info("U+00E9 writes %zu bytes, a surrogate writes %zu",
76 written_e9, written_surrogate);
77
78 return 0;
79}
uint32_t bj_bool
Boolean type used throughout the Banjo API.
Definition api.h:264
#define BJ_TRUE
Boolean true value (1).
Definition api.h:282
#define bj_info(...)
Log a message using the BJ_LOG_INFO level.
Definition log.h:141
struct bj_str bj_str_from_cstr(const char *c_string)
Create a view from a NUL-terminated C string.
A borrowed view of a sequence of bytes.
Definition string.h:57
uint32_t value
Decoded code point, or the partial value for an error.
Definition unicode.h:68
enum bj_utf8_state state
Result of the decoding attempt.
Definition unicode.h:69
const char * bytes
The bytes covered by the report, borrowed from the view.
Definition unicode.h:67
size_t n_bytes
Number of bytes covered by the report.
Definition unicode.h:66
size_t byte_offset
Offset of the first byte in the view.
Definition unicode.h:65
size_t bj_utf8_scan(struct bj_str view, bj_utf8_fn callback, void *user_data)
Process every UTF-8 character or decoding error in a view.
bj_bool bj_utf8_validate(struct bj_str view, size_t *first_error)
Check whether a view contains only valid UTF-8.
size_t bj_utf8_encode(uint32_t value, char bytes[4])
Encode a Unicode code point as UTF-8.
bj_bool bj_utf8_next(struct bj_str view, size_t *cursor, struct bj_utf8_report *report)
Read one UTF-8 character or decoding error from a view.
@ BJ_UTF8_STATE_VALID
A valid UTF-8 character was decoded.
Definition unicode.h:44
Details about one UTF-8 decoding attempt.
Definition unicode.h:64
Logging utility functions.
Portable main() replacement with platform-aware entry shim.
UTF-8 string views and owning strings.
int main(void)
Read, write and validate UTF-8 characters.
static bj_bool print_report(const struct bj_utf8_report *report, void *user_data)
Definition utf8_decode.c:23