Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Strings
Collaboration diagram for Strings:

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)

Detailed Description

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.

String views and owning strings

  • bj_str is a lightweight view of bytes. It borrows the memory, so creating or copying a view does not allocate memory. Its length is in bytes.
  • bj_string owns its memory and keeps its contents valid UTF-8. Invalid UTF-8 is replaced with U+FFFD when bytes are added to the string.

Working with C strings

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.

Warning
A bj_str is not NUL-terminated. Its 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.

Reading UTF-8 characters

The Unicode module provides functions to decode, encode and validate UTF-8. These functions work with the byte views defined here.


Data Structure Documentation

◆ bj_str

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.

Examples
strings.c, text_wrapper.c, and utf8_decode.c.

Definition at line 57 of file string.h.

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.

◆ bj_string

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.

Examples
strings.c.

Macro Definition Documentation

◆ BJ_STR

#define BJ_STR ( literal)
Value:
((struct bj_str){ "" literal "", sizeof(literal) - 1 })
A borrowed view of a sequence of bytes.
Definition string.h:57

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.

Examples
stream_file.c, strings.c, and text_wrapper.c.

Definition at line 75 of file string.h.

Referenced by main(), main(), and write_text().

◆ bj_strcmp

#define bj_strcmp   strcmp

Compare two NUL-terminated C strings.

This is an alias for the standard C library function strcmp.

Deprecated
Use bj_str_eq to compare two string views. This alias will be removed in 2.0.
Parameters
left_stringFirst NUL-terminated string.
right_stringSecond NUL-terminated string.
Returns
A value less than, equal to, or greater than zero when the first string is lexicographically less than, equal to, or greater than the second string.

Definition at line 252 of file string.h.

◆ bj_strlen

#define bj_strlen   strlen

Get the length of a NUL-terminated C string.

This is an alias for the standard C library function strlen.

Deprecated
Use bj_str_from_cstr to create a view with its length. This alias will be removed in 2.0.
Parameters
c_stringNUL-terminated string.
Returns
Number of bytes before the terminating NUL byte.

Definition at line 234 of file string.h.

Function Documentation

◆ bj_append_string()

void bj_append_string ( struct bj_string * string,
struct bj_str tail )

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.

Parameters
[in,out]stringThe string to extend. NULL is allowed and does nothing.
[in]tailBytes to append.
Examples
strings.c.

Referenced by main().

◆ bj_create_string()

struct bj_string * bj_create_string ( struct bj_str initial)

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.

Parameters
[in]initialBytes to copy into the string.
Returns
The new string, or NULL if memory allocation fails. An empty input creates a valid empty string.
Examples
strings.c.

Referenced by main().

◆ bj_destroy_string()

void bj_destroy_string ( struct bj_string * string)

Destroy an owning string and release its memory.

Parameters
[in]stringThe string to destroy. NULL is allowed.
Examples
strings.c.

Referenced by main().

◆ bj_str_eq()

bj_bool bj_str_eq ( struct bj_str left,
struct bj_str right )

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.

Parameters
[in]leftFirst view.
[in]rightSecond view.
Returns
BJ_TRUE when both views contain the same bytes, BJ_FALSE otherwise. Two empty views are equal.
Examples
strings.c.

Referenced by main().

◆ bj_str_from_cstr()

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.

Parameters
[in]c_stringThe NUL-terminated string, or NULL for an empty view.
Returns
A view of the bytes before the first NUL byte. Returns an empty view when c_string is NULL.
Examples
strings.c, and utf8_decode.c.

Referenced by bj_str_from_cstr(), and main().

◆ bj_str_slice()

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.

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.

Parameters
[in]viewThe view to slice.
[in]fromFirst byte to include.
[in]toOffset of the first byte to exclude.
Returns
A view borrowing the selected bytes. If the range is reversed or extends past the end of view, a debug build triggers an assertion and a release build returns an empty view.
Examples
strings.c.

Referenced by bj_str_slice(), and main().

◆ bj_string_cstr()

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.

Parameters
[in]stringThe string to read, or NULL.
Returns
A NUL-terminated pointer to the string's contents, or NULL when string is NULL. An embedded U+0000 ends the string when read by C functions that use NUL termination.
Examples
strings.c.

Referenced by main().

◆ bj_string_view()

struct bj_str bj_string_view ( const struct bj_string * string)

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.

Parameters
[in]stringThe string to read, or NULL for an empty view.
Returns
A view of the string's contents. The terminating NUL byte is not included.
Examples
strings.c.

Referenced by bj_string_view(), and main().