|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
Topics | |
| Unicode | |
Data Structures | |
| struct | bj_str |
| struct | bj_string |
Macros | |
| #define | BJ_STR(literal) |
| #define | bj_strlen strlen |
| #define | bj_strcmp strcmp |
Functions | |
| struct bj_str | bj_str_from_cstr (const char *c_string) |
| bj_bool | bj_str_eq (struct bj_str left, struct bj_str right) |
| struct bj_str | bj_str_slice (struct bj_str view, size_t from, size_t to) |
| struct bj_string * | bj_create_string (struct bj_str initial) |
| void | bj_destroy_string (struct bj_string *string) |
| struct bj_str | bj_string_view (const struct bj_string *string) |
| const char * | bj_string_cstr (const struct bj_string *string) |
| void | bj_append_string (struct bj_string *string, struct bj_str tail) |
Work with UTF-8 text using borrowed views and owning strings.
Banjo uses UTF-8 for text. This module provides two ways to work with it: bj_str for reading existing bytes, and bj_string for storing and building text.
Use BJ_STR for string literals and bj_str_from_cstr for NUL-terminated C strings. Both produce a bj_str. Use bj_string_cstr to get a NUL-terminated pointer from a bj_string.
data member points to exactly len bytes; do not pass it to functions such as printf with the s format. Use bj_string_cstr when a NUL-terminated string is required.The Unicode module provides functions to decode, encode and validate UTF-8. These functions work with the byte views defined here.
| struct bj_str |
A borrowed view of a sequence of bytes.
A view stores a pointer and a byte length. It does not own or copy the bytes, so the memory must remain available for as long as the view is used.
A view may contain any bytes; creating one does not check whether they form valid UTF-8. Its range is defined by len, not by a terminating NUL byte. The empty view can be represented by data == NULL and len == 0.
| Data Fields | ||
|---|---|---|
| const char * | data | Pointer to the first byte, or NULL for an empty view. |
| size_t | len | Number of bytes in the view. |
| struct bj_string |
An owning string containing valid UTF-8.
A bj_string owns its bytes and keeps them valid UTF-8. When it is created or extended, each ill-formed UTF-8 sequence is replaced with U+FFFD.
The string also stores a NUL byte after its contents. That byte is not included in the string's length or view, and allows the string to be passed to C functions that expect a NUL-terminated string.
U+0000 is also allowed as a character inside the string. C functions that read the string as a NUL-terminated string will stop at that character.
| #define BJ_STR | ( | literal | ) |
Create a view of a string literal.
The view's length is calculated at compile time. No allocation or runtime length calculation is needed.
The argument must be a string literal. Passing a pointer or another expression that is not a string literal causes a compile-time error.
Definition at line 75 of file string.h.
Referenced by main(), main(), and write_text().
| #define bj_strcmp strcmp |
Compare two NUL-terminated C strings.
This is an alias for the standard C library function strcmp.
| left_string | First NUL-terminated string. |
| right_string | Second NUL-terminated string. |
| #define bj_strlen strlen |
Get the length of a NUL-terminated C string.
This is an alias for the standard C library function strlen.
| c_string | NUL-terminated string. |
Append bytes to an owning string.
The bytes are copied to the end of the string. Ill-formed UTF-8 in the appended bytes is replaced with U+FFFD, using the same rules as bj_create_string.
| [in,out] | string | The string to extend. NULL is allowed and does nothing. |
| [in] | tail | Bytes to append. |
Referenced by main().
Create an owning string from a byte view.
The input bytes are copied into a new string. Ill-formed UTF-8 is replaced with U+FFFD. Each failed decoding report produces one replacement character. For example, the byte sequence E0 80 AF produces three replacement characters.
| [in] | initial | Bytes to copy into the string. |
Referenced by main().
| void bj_destroy_string | ( | struct bj_string * | string | ) |
Compare two views byte by byte.
The views are equal when they have the same length and contain the same bytes. This is a byte comparison; visually identical text with different UTF-8 encodings is considered different.
| [in] | left | First view. |
| [in] | right | Second view. |
Referenced by main().
| struct bj_str bj_str_from_cstr | ( | const char * | c_string | ) |
Create a view from a NUL-terminated C string.
The function measures the string up to its first NUL byte, as strlen does. The returned view borrows the original memory.
| [in] | c_string | The NUL-terminated string, or NULL for an empty view. |
c_string is NULL. Referenced by bj_str_from_cstr(), and main().
Create a view of a byte range within another view.
The range starts at from and ends just before to. Both offsets are measured in bytes. They do not have to fall on UTF-8 character boundaries.
| [in] | view | The view to slice. |
| [in] | from | First byte to include. |
| [in] | to | Offset of the first byte to exclude. |
view, a debug build triggers an assertion and a release build returns an empty view. Referenced by bj_str_slice(), and main().
| const char * bj_string_cstr | ( | const struct bj_string * | string | ) |
Get a NUL-terminated pointer to an owning string.
The returned pointer refers to memory owned by the string. It remains valid until the string is appended to or destroyed.
| [in] | string | The string to read, or NULL. |
string is NULL. An embedded U+0000 ends the string when read by C functions that use NUL termination. Referenced by main().
Get a borrowed view of an owning string.
The returned view points to the string's bytes. It remains valid until the string is modified or destroyed.
| [in] | string | The string to read, or NULL for an empty view. |
Referenced by bj_string_view(), and main().