Strings

Strings are represented in UTF-8, using the WGPUStringView struct:

‍

Nullable value defining a pointer+length view into a UTF-8 encoded string.

Values passed into the API may use the special length value WGPU_STRLEN to indicate a null-terminated string. Non-null values passed out of the API (for example as callback arguments) always provide an explicit length and may or may not be null-terminated.

Some inputs to the API accept null values. Those which do not accept null values "default" to the empty string when null values are passed.

Values are encoded as follows:

• {NULL, WGPU_STRLEN}: the null value.
• {non_null_pointer, WGPU_STRLEN}: a null-terminated string view.
• {any, 0}: the empty string.
• {NULL, non_zero_length}: not allowed (null dereference).
• {non_null_pointer, non_zero_length}: an explictly-sized string view with size non_zero_length (in bytes).

For info on how this is used in various places, see Strings.

Nullable Input String

An input string where the null value may be treated separately from the empty string (e.g. to indicate the absence of a string, or to run some non-trivial defaulting algorithm).

Non-Null Input String

This input string is non-nullable. If the null value is passed, it is treated as the empty string.

Output String

This output string is always explicitly sized and never the null value. There is no null terminator inside the string; there may or may not be one after the end. If empty, the data pointer may or may not be null.

To format explicitly-sized strings with printf, use %.*s (s with a "precision" argument .* specifying the max number of bytes to read from the pointer).

Localizable Human-Readable Message String

This is a Output String which is human-readable and implementation-dependent, and may be locale-dependent. It should not be parsed or otherwise treated as machine-readable.