Unicode

touchgfx/Unicode.hpp

This class provides simple helper functions for working with strings which are stored as a null-terminated array of 16-bit characters.

Public Types

typedef uint16_t	UnicodeChar
	Use the UnicodeChar typename when referring to characters in a string.

Public Functions

int	atoi(const UnicodeChar * s)
	String to integer conversion.
uint16_t	fromUTF8(const uint8_t utf8, UnicodeChar dst, uint16_t maxchars)
	Convert a string from UTF8 to Unicode.
void	itoa(int32_t value, UnicodeChar * buffer, uint16_t bufferSize, int radix)
	Integer to ASCII conversion.
UnicodeChar *	snprintf(UnicodeChar dst, uint16_t dstSize, const char format, ... )
	Formats a string and adds null termination.
UnicodeChar *	snprintf(UnicodeChar dst, uint16_t dstSize, const UnicodeChar format, ... )
	Formats a string and adds null termination.
UnicodeChar *	snprintfFloat(UnicodeChar dst, uint16_t dstSize, const char format, const float value)
	Variant of snprintfFloats() for exactly one float only.
UnicodeChar *	snprintfFloat(UnicodeChar dst, uint16_t dstSize, const UnicodeChar format, const float value)
	Variant of snprintfFloats() for exactly one float only.
UnicodeChar *	snprintfFloats(UnicodeChar dst, uint16_t dstSize, const char format, const float * values)
	Variant of snprintf for floats only.
UnicodeChar *	snprintfFloats(UnicodeChar dst, uint16_t dstSize, const UnicodeChar format, const float * values)
	Variant of snprintf for floats only.
uint16_t	strlen(const char * str)
	Gets the length of a null-terminated string.
uint16_t	strlen(const UnicodeChar * str)
	Gets the length of a null-terminated Unicode string.
int	strncmp(const UnicodeChar RESTRICT str1, const UnicodeChar RESTRICT str2, uint16_t maxchars)
	Compares up to maxchars characters in two strings.
int	strncmp_ignore_whitespace(const UnicodeChar RESTRICT str1, const UnicodeChar RESTRICT str2, uint16_t maxchars)
	Like strncmp except that ignore any whitespaces in the two strings.
uint16_t	strncpy(UnicodeChar RESTRICT dst, const char RESTRICT src, uint16_t maxchars)
	Copy a string to a destination buffer, char to UnicodeChar version.
uint16_t	strncpy(UnicodeChar RESTRICT dst, const UnicodeChar RESTRICT src, uint16_t maxchars)
	Copy a string to a destination buffer, UnicodeChar to UnicodeChar version.
uint16_t	toUTF8(const UnicodeChar unicode, uint8_t utf8, uint16_t maxbytes)
	Converts a string from Unicode to UTF8.
void	utoa(uint32_t value, UnicodeChar * buffer, uint16_t bufferSize, int radix)
	Integer to ASCII conversion.
UnicodeChar *	vsnprintf(UnicodeChar dst, uint16_t dstSize, const char format, va_list pArg)
	Variant of snprintf.
UnicodeChar *	vsnprintf(UnicodeChar dst, uint16_t dstSize, const UnicodeChar format, va_list pArg)
	Variant of snprintf.

Public Types Documentation

UnicodeChar

typedef uint16_t UnicodeChar

Use the UnicodeChar typename when referring to characters in a string.

Public Functions Documentation

atoi

static int atoi	(	const UnicodeChar *	s	)

String to integer conversion.

Starts conversion at the start of the string. Running digits from here are converted. Only radix 10 supported.

Parameters:

s	Radix 10, null-terminated Unicode string to convert.

Returns:

The converted integer value of the string, 0 if the string does not start with a digit.

fromUTF8

static uint16_t fromUTF8	(	const uint8_t *	utf8 ,
		UnicodeChar *	dst ,
		uint16_t	maxchars
		)

Convert a string from UTF8 to Unicode.

The conversion stops if there is no more room in the destination or if the terminating zero character has been converted.

Parameters:

utf8	The UTF8 string.
dst	The destination buffer for the converted string.
maxchars	The maximum number of chars that the dst array can hold.

Returns:

The number of characters successfully converted from UTF8 to Unicode including the terminating zero.

itoa

static void itoa	(	int32_t	value ,
		UnicodeChar *	buffer ,
		uint16_t	bufferSize ,
		int	radix
		)

Integer to ASCII conversion.

Supports radix 2 to radix 36.

Parameters:

value	to convert.
buffer	to place result in.
bufferSize	Size of buffer (number of UnicodeChar's).
radix	to use (8 for octal, 10 for decimal, 16 for hex)

snprintf

static UnicodeChar * snprintf	(	UnicodeChar *	dst ,
		uint16_t	dstSize ,
		const char *	format ,
		...
		)

Formats a string and adds null termination.

The string is formatted like when the standard printf is used.

Support formats: %c (element type: char), %s (element type: null-terminated UnicodeChar list), %u, %i, %d, %o, %x (all these are integers formatted in radix 10, 10, 10, 8, 16 respectively).

The number formats (%u, %i, %d, %o and %x) all support

\%[flags][width][.precision]X

Where flags can be:

• '-': left justify the field (see width).
• '+': force sign.
• ' ': insert space if value is positive.
• '0': left pad with zeros instead of spaces (see width). Where width is the desired width of the output. If the value is larger, more characters may be generated, but not more than the parameter dstSize. If width is '*' the actual width is read from the parameters passed to this function.

Where precision is the number of number of digits after the decimal point, default is

1. Use "\%.f" to not generate any numbers after the decimal point. If precision is '*' the actual precision is read from the parameters passed to this function.

Parameters:

dst	Buffer for the formatted string.
dstSize	Size of the dst buffer measured by number of UnicodeChars the buffer can hold.
format	The format string.
...	The values to insert in the format string.

Returns:

pointer to the first element in the buffer where the formatted string is placed.

Note

%f is not supported by this function because floats are converted to doubles when given as parameters in a variable argument list (va_list). Use snprintfFloat or snprintfFloats instead.

See also:

snprintfFloat, snprintfFloats snprintfFloat, snprintfFloats

snprintf

static UnicodeChar * snprintf	(	UnicodeChar *	dst ,
		uint16_t	dstSize ,
		const UnicodeChar *	format ,
		...
		)

Formats a string and adds null termination.

The string is formatted like when the standard printf is used.

Support formats: %c (element type: char), %s (element type: null-terminated UnicodeChar list), %u, %i, %d, %o, %x (all these are integers formatted in radix 10, 10, 10, 8, 16 respectively).

The number formats (%u, %i, %d, %o and %x) all support %[0][length]X to specify the size of the generated field (length) and whether the number should be prefixed with zeros (or blanks).

Parameters:

dst	Buffer for the formatted string.
dstSize	Size of the dst buffer measured by number of UnicodeChars the buffer can hold.
format	The format string.
...	The values to insert in the format string.

Returns:

pointer to the first element in the buffer where the formatted string is placed.

Note

%f is not supported by this function because floats are converted to doubles when given as parameters in a variable argument list (va_list). Use snprintfFloat or snprintfFloats instead.

See also:

snprintfFloat, snprintfFloats

snprintfFloat

static UnicodeChar * snprintfFloat	(	UnicodeChar *	dst ,
		uint16_t	dstSize ,
		const char *	format ,
		const float	value
		)

Variant of snprintfFloats() for exactly one float only.

The number format supports only one %f with flags/modifiers. The following is supported:

\%[flags][width][.precision]f

Where flags can be:

• '-': left justify the field (see width).
• '+': force sign.
• ' ': insert space if value is positive.
• '#': insert decimal point even if there are not decimals.
• '0': left pad with zeros instead of spaces (see width). Where width is the desired width of the output. If the value is larger, more characters may be generated, but not more than the parameter dstSize.

Where precision is the number of number of digits after the decimal point, default is "3". Use "\%.f" to not generate any numbers after the decimal point.

Unicode::UnicodeChar buffer[20];
Unicode::snprintfFloat(buffer, 20, "%6.4f", 3.14159f);
// buffer="3.1416"
Unicode::snprintfFloat(buffer, 20, "%#6.f", 3.14159f);
// buffer="    3."
Unicode::snprintfFloat(buffer, 20, "%6f", 3.14159f);
// buffer=" 3.142"
Unicode::snprintfFloat(buffer, 20, "%+06.f", 3.14159f);
// buffer="+00003"

Filename: .cpp

If more control over the output is needed, see snprintfFloats which can have more than a single "\%f" in the string and also supports "*" in place of a number.

Parameters:

dst	Buffer for the formatted string.
dstSize	Size of the dst buffer measured by number of UnicodeChars the buffer can hold.
format	The format string containing exactly on occurrence of f.
value	The floating point value to insert for f.

Returns:

pointer to the first element in the buffer where the formatted string is placed.

See also:

snprintf, snprintfFloats

snprintfFloat

static UnicodeChar * snprintfFloat	(	UnicodeChar *	dst ,
		uint16_t	dstSize ,
		const UnicodeChar *	format ,
		const float	value
		)

Variant of snprintfFloats() for exactly one float only.

The number format supports only one %f with flags/modifiers. The following is supported:

\%[flags][width][.precision]f

Where flags can be:

• '-': left justify the field (see width).
• '+': force sign.
• ' ': insert space if value is positive.
• '#': insert decimal point even if there are not decimals.
• '0': left pad with zeros instead of spaces (see width). Where width is the desired width of the output. If the value is larger, more characters may be generated, but not more than the parameter dstSize.

Where precision is the number of number of digits after the decimal point, default is "3". Use "\%.f" to not generate any numbers after the decimal point.

Unicode::UnicodeChar buffer[20];
Unicode::snprintfFloat(buffer, 20, "%6.4f", 3.14159f);
// buffer="3.1416"
Unicode::snprintfFloat(buffer, 20, "%#6.f", 3.14159f);
// buffer="    3."
Unicode::snprintfFloat(buffer, 20, "%6f", 3.14159f);
// buffer=" 3.142"
Unicode::snprintfFloat(buffer, 20, "%+06.f", 3.14159f);
// buffer="+00003"

Filename: .cpp

If more control over the output is needed, see snprintfFloats which can have more than a single "\%f" in the string and also supports "*" in place of a number.

Parameters:

dst	Buffer for the formatted string.
dstSize	Size of the dst buffer measured by number of UnicodeChars the buffer can hold.
format	The format string containing exactly on occurrence of f.
value	The floating point value to insert for f.

Returns:

pointer to the first element in the buffer where the formatted string is placed.

See also:

snprintf, snprintfFloats

snprintfFloats

static UnicodeChar * snprintfFloats	(	UnicodeChar *	dst ,
		uint16_t	dstSize ,
		const char *	format ,
		const float *	values
		)

Variant of snprintf for floats only.

The format supports several %f with flags/modifiers. The following is supported:

\%[flags][width][.precision]f

Where flags can be:

• '-': left justify the field (see width).
• '+': force sign.
• ' ': insert space if value is positive
• '#': insert decimal point even if there are not decimals
• '0': left pad with zeros instead of spaces (see width) Where width is the desired width of the output. If the value is larger, more characters may be generated, but not more than the parameter dstSize. If width is '*' the actual width is read from the list of values passed to this function.

Where precision is the number of number of digits after the decimal point, default is

1. Use "\%.f" to not generate any numbers after the decimal point. If precision is '*' the actual precision is read from the list of values passed to this function.

float param1[3] = { 6.0f, 4.0f, 3.14159f };
Unicode::snprintfFloats(buffer, 20, "%*.*f", param1);
// buffer="3.1416" float param2[2] = { 3.14159f, -123.4f };
Unicode::snprintfFloats(buffer, 20, "%f %f", param2);
// buffer="3.142 -123.400"

Filename: .cpp

Parameters:

dst	Buffer for the formatted string.
dstSize	Size of the dst buffer measured by number of UnicodeChars the buffer can hold.
format	The format string containing f's.
values	The floating point values to insert for f. The number of elements in the array must match the number of f's in the format string.

Returns:

pointer to the first element in the buffer where the formatted string is placed.

See also:

snprintf, snprintfFloat

snprintfFloats

static UnicodeChar * snprintfFloats	(	UnicodeChar *	dst ,
		uint16_t	dstSize ,
		const UnicodeChar *	format ,
		const float *	values
		)

Variant of snprintf for floats only.

The format supports several %f with flags/modifiers. The following is supported:

\%[flags][width][.precision]f

Where flags can be:

• '-': left justify the field (see width).
• '+': force sign.
• ' ': insert space if value is positive
• '#': insert decimal point even if there are not decimals
• '0': left pad with zeros instead of spaces (see width) Where width is the desired width of the output. If the value is larger, more characters may be generated, but not more than the parameter dstSize. If width is '*' the actual width is read from the list of values passed to this function.

Where precision is the number of number of digits after the decimal point, default is

1. Use "\%.f" to not generate any numbers after the decimal point. If precision is '*' the actual precision is read from the list of values passed to this function.

float param1[3] = { 6.0f, 4.0f, 3.14159f };
Unicode::snprintfFloats(buffer, 20, "%*.*f", param1);
// buffer="3.1416" float param2[2] = { 3.14159f, -123.4f };
Unicode::snprintfFloats(buffer, 20, "%f %f", param2);
// buffer="3.142 -123.400"

Filename: .cpp

Parameters:

dst	Buffer for the formatted string.
dstSize	Size of the dst buffer measured by number of UnicodeChars the buffer can hold.
format	The format string containing f's.
values	The floating point values to insert for f. The number of elements in the array must match the number of f's in the format string.

Returns:

pointer to the first element in the buffer where the formatted string is placed.

See also:

snprintf, snprintfFloat

strlen

static uint16_t strlen	(	const char *	str	)

Gets the length of a null-terminated string.

Parameters:

str	The string.

Returns:

Length of string.

strlen

static uint16_t strlen	(	const UnicodeChar *	str	)

Gets the length of a null-terminated Unicode string.

Parameters:

str	The string in question.

Returns:

Length of string.

strncmp

static int strncmp	(	const UnicodeChar *RESTRICT	str1 ,
		const UnicodeChar *RESTRICT	str2 ,
		uint16_t	maxchars
		)

Compares up to maxchars characters in two strings.

One character from each buffer is compared, one at a time until the characters differ, until a terminating null- character is reached, or until maxchars characters match in both strings, whichever happens first.

Parameters:

str1	The first string.
str2	The second string.
maxchars	The maximum number of chars to compare.

Returns:

Returns an integral value indicating the relationship between the strings: A zero value indicates that the characters compared in both strings are all equal. A value greater than zero indicates that the first character that does not match has a greater value in str1 than in str2; And a value less than zero indicates the opposite.

strncmp_ignore_whitespace

static int strncmp_ignore_whitespace	(	const UnicodeChar *RESTRICT	str1 ,
		const UnicodeChar *RESTRICT	str2 ,
		uint16_t	maxchars
		)

Like strncmp except that ignore any whitespaces in the two strings.

Parameters:

str1	The first string.
str2	The second string.
maxchars	The maximum number of chars to compare.

Returns:

Returns an integral value indicating the relationship between the strings: A zero value indicates that the characters compared in both strings are all equal. A value greater than zero indicates that the first character that does not match has a greater value in str1 than in str2; And a value less than zero indicates the opposite.

strncpy

static uint16_t strncpy	(	UnicodeChar *RESTRICT	dst ,
		const char *RESTRICT	src ,
		uint16_t	maxchars
		)

Copy a string to a destination buffer, char to UnicodeChar version.

Stops after copying maxchars Unicode characters or after copying the ending null-termination UnicodeChar.

Parameters:

dst	The destination buffer. Must have a size of at least maxchars.
src	The source string.
maxchars	Maximum number of chars to copy.

Returns:

The number of characters copied (excluding null-termination if encountered)

Note

If there is no null-termination among the first n UnicodeChars of src, the string placed in destination will NOT be null-terminated!

strncpy

static uint16_t strncpy	(	UnicodeChar *RESTRICT	dst ,
		const UnicodeChar *RESTRICT	src ,
		uint16_t	maxchars
		)

Copy a string to a destination buffer, UnicodeChar to UnicodeChar version.

Stops after copying maxchars Unicode characters or after copying the ending zero termination UnicodeChar.

Parameters:

dst	The destination buffer. Must have a size of at least maxchars.
src	The source string.
maxchars	Maximum number of UnicodeChars to copy.

Returns:

The number of characters copied (excluding null-termination if encountered)

Note

If there is no null-termination among the first n UnicodeChars of src, the string placed in destination will NOT be null-terminated!

toUTF8

static uint16_t toUTF8	(	const UnicodeChar *	unicode ,
		uint8_t *	utf8 ,
		uint16_t	maxbytes
		)

Converts a string from Unicode to UTF8.

The conversion stops if there is no more room in the destination or if the terminating zero character has been converted. U+10000 through U+10FFFF are skipped.

Parameters:

unicode	The Unicode string.
utf8	The destination buffer for the converted string.
maxbytes	The maximum number of bytes that the UTF8 array can hold.

Returns:

The number of characters successfully converted from Unicode to UTF8 including the terminating zero.

utoa

static void utoa	(	uint32_t	value ,
		UnicodeChar *	buffer ,
		uint16_t	bufferSize ,
		int	radix
		)

Integer to ASCII conversion.

Supports radix 2 to radix 36.

Parameters:

value	to convert.
buffer	to place result in.
bufferSize	Size of buffer (number of UnicodeChar's).
radix	to use (8 for octal, 10 for decimal, 16 for hex)

vsnprintf

static UnicodeChar * vsnprintf	(	UnicodeChar *	dst ,
		uint16_t	dstSize ,
		const char *	format ,
		va_list	pArg
		)

Variant of snprintf.

Parameters:

dst	Buffer for the formatted string.
dstSize	Size of the dst buffer measured by number of UnicodeChars the buffer can hold.
format	The format string.
pArg	The values to insert in the format string.

Returns:

pointer to the first element in the buffer where the formatted string is placed.

See also:

snprintf

vsnprintf

static UnicodeChar * vsnprintf	(	UnicodeChar *	dst ,
		uint16_t	dstSize ,
		const UnicodeChar *	format ,
		va_list	pArg
		)

Variant of snprintf.

Parameters:

dst	Buffer for the formatted string.
dstSize	Size of the dst buffer measured by number of UnicodeChars the buffer can hold.
format	The format string.
pArg	The values to insert in the format string.

Returns:

pointer to the first element in the buffer where the formatted string is placed.

See also:

snprintf