Strings (explicit display normalisation)

Optional UTF-8 <-> display-codepage conversion helpers. More...

Macros
#define	HOST_STR_TARGET_CP437   0 /* GFX builtin glcdfont (default after splash) */
	Target codepage for host_str_to_display().
#define	HOST_STR_TARGET_LATIN1   1 /* FreeMonoBold*pt8b fonts (Latin-1 indexed) */

Functions
int	host_str_to_display (const char *in, char *out, size_t out_size, uint32_t target)
	Decode HTML entities + UTF-8 in in into single-byte display characters in out.
int	host_str_to_utf8 (const char *in, char *out, size_t out_size)
	Convert CP437 display bytes in in to a UTF-8 string in out.

Detailed Description

Optional UTF-8 <-> display-codepage conversion helpers.

The whole host API speaks UTF-8: text passed to UI / canvas / display functions is converted to the display codepage internally, and text read back (host_ui_consume_input_text, host_view_canvas_get_text) is returned as UTF-8. Plugins normally never need to convert anything themselves.

These two helpers remain for advanced cases, e.g. pre-rendering a string to a specific codepage. Do not feed their output back into the auto-converting UI functions, or the text is encoded twice.

Macro Definition Documentation

HOST_STR_TARGET_CP437

#define HOST_STR_TARGET_CP437   0 /* GFX builtin glcdfont (default after splash) */

Target codepage for host_str_to_display().

Definition at line 1437 of file host_api.h.

HOST_STR_TARGET_LATIN1

#define HOST_STR_TARGET_LATIN1   1 /* FreeMonoBold*pt8b fonts (Latin-1 indexed) */

Definition at line 1438 of file host_api.h.

Referenced by host_str_to_display().

Function Documentation

host_str_to_display()

int host_str_to_display	(	const char *	in,
		char *	out,
		size_t	out_size,
		uint32_t	target )

Decode HTML entities + UTF-8 in in into single-byte display characters in out.

Optional: the UI / canvas / display functions already perform this on the text you pass them. target selects the output codepage. Unknown codepoints are dropped. Truncates if the result would exceed out_size - 1 bytes. Output is always NUL-terminated.

Parameters

in	Source string (UTF-8 with optional HTML entities).
out	Destination buffer.
out_size	Capacity of out in bytes (including the NUL).
target	One of HOST_STR_TARGET_*.

Returns

HOST_OK on success, HOST_ERR_INVALID_ARG when inputs are NULL or out_size==0.

Definition at line 14 of file host_api_strings.cpp.

References cdc::ui::render::Cp437, cdc::ui::render::decodeWebText(), HOST_ERR_INVALID_ARG, HOST_OK, HOST_STR_TARGET_LATIN1, and cdc::ui::render::Latin1.

Referenced by cdc::plugin_manager::w_host_str_to_display().

host_str_to_utf8()

int host_str_to_utf8	(	const char *	in,
		char *	out,
		size_t	out_size )

Convert CP437 display bytes in in to a UTF-8 string in out.

Optional: host_ui_consume_input_text and host_view_canvas_get_text already return UTF-8.

Parameters

in	Source CP437 string.
out	Destination buffer (always NUL-terminated, truncated to fit).
out_size	Capacity of out in bytes (including the NUL).

Returns

Bytes written (excluding NUL), or a negative HOST_ERR_* code.

Definition at line 24 of file host_api_strings.cpp.

References cdc::plugin_manager::copyUtf8().

Referenced by cdc::plugin_manager::w_host_str_to_utf8().