|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
Data Structures | |
| struct | bj_utf8_report |
Typedefs | |
| typedef bj_bool(* | bj_utf8_fn) (const struct bj_utf8_report *report, void *user_data) |
Enumerations | |
| enum | bj_utf8_state { BJ_UTF8_STATE_VALID = 0 , BJ_UTF8_STATE_BAD_LEAD , BJ_UTF8_STATE_LONE_CONTINUATION , BJ_UTF8_STATE_BAD_SLOT , BJ_UTF8_STATE_TRUNCATED } |
Functions | |
| bj_bool | bj_utf8_next (struct bj_str view, size_t *cursor, struct bj_utf8_report *report) |
| size_t | bj_utf8_scan (struct bj_str view, bj_utf8_fn callback, void *user_data) |
| bj_bool | bj_utf8_prev (struct bj_str view, size_t *cursor, uint32_t *value) |
| size_t | bj_utf8_encode (uint32_t value, char bytes[4]) |
| bj_bool | bj_utf8_validate (struct bj_str view, size_t *first_error) |
Decode and encode UTF-8 text.
UTF-8 represents each Unicode character with one to four bytes. This module provides functions to read those characters, write them as UTF-8, and check whether a byte sequence is valid.
Use bj_utf8_next to read one character at a time, or bj_utf8_scan to process an entire view with a callback. Each read produces a bj_utf8_report describing the bytes and the result.
When a byte sequence is malformed, the decoder reports the valid prefix of the attempted character and leaves the byte that caused the error for the next read. This lets decoding continue after malformed input without losing subsequent valid characters. For example, E0 80 AF produces three failed reports.
Use bj_utf8_validate to check input before storing or processing it. The string constructor bj_create_string instead replaces malformed sequences with U+FFFD.
| struct bj_utf8_report |
Details about one UTF-8 decoding attempt.
Each report describes the bytes consumed by one call to bj_utf8_next. For a valid character, value contains its Unicode code point. For an error, value contains the bits decoded before the error was detected.
A failed report covers the part of the sequence that could still have been valid. The byte that caused the error is left for the next decoding attempt. As a result, every input byte belongs to exactly one report.
| Data Fields | ||
|---|---|---|
| size_t | byte_offset | Offset of the first byte in the view. |
| const char * | bytes | The bytes covered by the report, borrowed from the view. |
| size_t | n_bytes | Number of bytes covered by the report. |
| enum bj_utf8_state | state | Result of the decoding attempt. |
| uint32_t | value | Decoded code point, or the partial value for an error. |
| typedef bj_bool(* bj_utf8_fn) (const struct bj_utf8_report *report, void *user_data) |
Callback used by bj_utf8_scan.
| report | Details about the current decoding result. The report is only valid for the duration of the callback. |
| user_data | The pointer supplied to bj_utf8_scan. |
| enum bj_utf8_state |
Result of decoding the bytes in a UTF-8 report.
| size_t bj_utf8_encode | ( | uint32_t | value, |
| char | bytes[4] ) |
Encode a Unicode code point as UTF-8.
The function writes the shortest valid UTF-8 sequence for value. Surrogate values (U+D800 to U+DFFF) and values above U+10FFFF cannot be encoded.
| [in] | value | Code point to encode. |
| [out] | bytes | Buffer that can hold four bytes. |
value cannot be encoded or bytes is NULL. The buffer is unchanged when zero is returned. Referenced by main().
| 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.
The function reads from the byte offset in cursor and advances the cursor past the bytes described by the report. The cursor may point to any byte, including the middle of a multi-byte character.
| [in] | view | Bytes to read. |
| [in,out] | cursor | Byte offset to read from. It is advanced when a report is produced. If it is at or past the end of the view, it is left unchanged. |
| [out] | report | Receives the decoding result. May be NULL if you only need to advance the cursor. |
Referenced by main().
Read the UTF-8 character immediately before a byte offset.
The function moves cursor back to the first byte of the character ending at that offset. The input must contain valid UTF-8.
| [in] | view | UTF-8 bytes to read. |
| [in,out] | cursor | Offset immediately after the character. On success, it is moved to the character's first byte. |
| [out] | value | Receives the decoded Unicode code point. |
cursor or value when the offset is zero, past the end of the view, or not at the end of a character. | 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.
The function calls callback once for each report produced by bj_utf8_next. Return BJ_FALSE from the callback to stop the scan.
| [in] | view | Bytes to read. |
| [in] | callback | Function called for each report, or NULL to count the reports without processing them. |
| [in] | user_data | Pointer passed to each callback invocation. |
Referenced by main().
Check whether a view contains only valid UTF-8.
The function reads the entire view and returns the byte offset of the first decoding error when one is found.
| [in] | view | Bytes to validate. |
| [out] | first_error | Receives the offset of the first invalid byte, or may be NULL if the offset is not needed. |
Referenced by main().