Skip to main content
Version: 4.16

Unicode

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_tUnicodeChar
Use the UnicodeChar typename when referring to characters in a string.

Public Functions#

intatoi(const UnicodeChar * s)
String to integer conversion.
uint16_tfromUTF8(const uint8_t utf8, UnicodeChar dst, uint16_t maxchars)
Convert a string from UTF8 to Unicode.
voiditoa(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_tstrlen(const char * str)
Gets the length of a null-terminated string.
uint16_tstrlen(const UnicodeChar * str)
Gets the length of a null-terminated Unicode string.
intstrncmp(const UnicodeChar RESTRICT str1, const UnicodeChar RESTRICT str2, uint16_t maxchars)
Compares up to maxchars characters in two strings.
intstrncmp_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_tstrncpy(UnicodeChar RESTRICT dst, const char RESTRICT src, uint16_t maxchars)
Copy a string to a destination buffer, char to UnicodeChar version.
uint16_tstrncpy(UnicodeChar RESTRICT dst, const UnicodeChar RESTRICT src, uint16_t maxchars)
Copy a string to a destination buffer, UnicodeChar to UnicodeChar version.
uint16_ttoUTF8(const UnicodeChar unicode, uint8_t utf8, uint16_t maxbytes)
Converts a string from Unicode to UTF8.
voidutoa(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:
sRadix 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_tmaxchars
)

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:
utf8The UTF8 string.
dstThe destination buffer for the converted string.
maxcharsThe 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_tvalue ,
UnicodeChar *buffer ,
uint16_tbufferSize ,
intradix
)

Integer to ASCII conversion.

Supports radix 2 to radix 36.

Parameters:
valueto convert.
bufferto place result in.
bufferSizeSize of buffer (number of UnicodeChar's).
radixto use (8 for octal, 10 for decimal, 16 for hex)

snprintf#

static UnicodeChar * snprintf(UnicodeChar *dst ,
uint16_tdstSize ,
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:
dstBuffer for the formatted string.
dstSizeSize of the dst buffer measured by number of UnicodeChars the buffer can hold.
formatThe 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:

snprintf#

static UnicodeChar * snprintf(UnicodeChar *dst ,
uint16_tdstSize ,
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:
dstBuffer for the formatted string.
dstSizeSize of the dst buffer measured by number of UnicodeChars the buffer can hold.
formatThe 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#

static UnicodeChar * snprintfFloat(UnicodeChar *dst ,
uint16_tdstSize ,
const char *format ,
const floatvalue
)

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:
dstBuffer for the formatted string.
dstSizeSize of the dst buffer measured by number of UnicodeChars the buffer can hold.
formatThe format string containing exactly on occurrence of f.
valueThe floating point value to insert for f.
Returns:

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

See also:

snprintfFloat#

static UnicodeChar * snprintfFloat(UnicodeChar *dst ,
uint16_tdstSize ,
const UnicodeChar *format ,
const floatvalue
)

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:
dstBuffer for the formatted string.
dstSizeSize of the dst buffer measured by number of UnicodeChars the buffer can hold.
formatThe format string containing exactly on occurrence of f.
valueThe floating point value to insert for f.
Returns:

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

See also:

snprintfFloats#

static UnicodeChar * snprintfFloats(UnicodeChar *dst ,
uint16_tdstSize ,
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:
dstBuffer for the formatted string.
dstSizeSize of the dst buffer measured by number of UnicodeChars the buffer can hold.
formatThe format string containing f's.
valuesThe 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:

snprintfFloats#

static UnicodeChar * snprintfFloats(UnicodeChar *dst ,
uint16_tdstSize ,
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:
dstBuffer for the formatted string.
dstSizeSize of the dst buffer measured by number of UnicodeChars the buffer can hold.
formatThe format string containing f's.
valuesThe 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:

strlen#

static uint16_t strlen(const char *str)

Gets the length of a null-terminated string.

Parameters:
strThe string.
Returns:

Length of string.

strlen#

static uint16_t strlen(const UnicodeChar *str)

Gets the length of a null-terminated Unicode string.

Parameters:
strThe string in question.
Returns:

Length of string.

strncmp#

static int strncmp(const UnicodeChar *RESTRICTstr1 ,
const UnicodeChar *RESTRICTstr2 ,
uint16_tmaxchars
)

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:
str1The first string.
str2The second string.
maxcharsThe 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 *RESTRICTstr1 ,
const UnicodeChar *RESTRICTstr2 ,
uint16_tmaxchars
)

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

Parameters:
str1The first string.
str2The second string.
maxcharsThe 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 *RESTRICTdst ,
const char *RESTRICTsrc ,
uint16_tmaxchars
)

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:
dstThe destination buffer. Must have a size of at least maxchars.
srcThe source string.
maxcharsMaximum 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 *RESTRICTdst ,
const UnicodeChar *RESTRICTsrc ,
uint16_tmaxchars
)

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:
dstThe destination buffer. Must have a size of at least maxchars.
srcThe source string.
maxcharsMaximum 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_tmaxbytes
)

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:
unicodeThe Unicode string.
utf8The destination buffer for the converted string.
maxbytesThe 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_tvalue ,
UnicodeChar *buffer ,
uint16_tbufferSize ,
intradix
)

Integer to ASCII conversion.

Supports radix 2 to radix 36.

Parameters:
valueto convert.
bufferto place result in.
bufferSizeSize of buffer (number of UnicodeChar's).
radixto use (8 for octal, 10 for decimal, 16 for hex)

vsnprintf#

static UnicodeChar * vsnprintf(UnicodeChar *dst ,
uint16_tdstSize ,
const char *format ,
va_listpArg
)

Variant of snprintf.

Parameters:
dstBuffer for the formatted string.
dstSizeSize of the dst buffer measured by number of UnicodeChars the buffer can hold.
formatThe format string.
pArgThe values to insert in the format string.
Returns:

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

See also:

vsnprintf#

static UnicodeChar * vsnprintf(UnicodeChar *dst ,
uint16_tdstSize ,
const UnicodeChar *format ,
va_listpArg
)

Variant of snprintf.

Parameters:
dstBuffer for the formatted string.
dstSizeSize of the dst buffer measured by number of UnicodeChars the buffer can hold.
formatThe format string.
pArgThe values to insert in the format string.
Returns:

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

See also: