The UTF-8 string functions handle string operations on UTF-8 encoded strings. More...

Macros
#define	RTUTF8STRCMPL(name, lstr) rtxUTF8Strcmp(name,(const OSUTF8CHAR*)lstr)
	Compare UTF-8 string to a string literal. More...

Functions
EXTERNRT long	rtxUTF8ToUnicode (OSCTXT pctxt, const OSUTF8CHAR inbuf, OSUNICHAR *outbuf, size_t outbufsiz)
	This function converts a UTF-8 string to a Unicode string (UTF-16). More...

EXTERNRT long	rtxUTF8ToUnicode32 (OSCTXT pctxt, const OSUTF8CHAR inbuf, OS32BITCHAR *outbuf, size_t outbufsiz)
	This function converts a UTF-8 string to a Unicode string (UTF-32). More...

EXTERNRT int	rtxValidateUTF8 (OSCTXT pctxt, const OSUTF8CHAR inbuf)
	This function will validate a UTF-8 encoded string to ensure that it is encoded correctly. More...

EXTERNRT size_t	rtxUTF8Len (const OSUTF8CHAR *inbuf)
	This function will return the length (in characters) of a null-terminated UTF-8 encoded string. More...

EXTERNRT size_t	rtxUTF8LenBytes (const OSUTF8CHAR *inbuf)
	This function will return the length (in bytes) of a null-terminated UTF-8 encoded string. More...

EXTERNRT int	rtxUTF8CharSize (OS32BITCHAR wc)
	This function will return the number of bytes needed to encode the given 32-bit universal character value as a UTF-8 character. More...

EXTERNRT int	rtxUTF8EncodeChar (OS32BITCHAR wc, OSOCTET *buf, size_t bufsiz)
	This function will convert a wide character into an encoded UTF-8 character byte string. More...

EXTERNRT int	rtxUTF8DecodeChar (OSCTXT pctxt, const OSUTF8CHAR pinbuf, int *pInsize)
	This function will convert an encoded UTF-8 character byte string into a wide character value. More...

EXTERNRT OS32BITCHAR	rtxUTF8CharToWC (const OSUTF8CHAR buf, OSUINT32 len)
	Thia function will convert a UTF-8 encoded character value into a wide character. More...

EXTERNRT OSUTF8CHAR *	rtxUTF8StrChr (OSUTF8CHAR *utf8str, OS32BITCHAR utf8char)
	This function finds a character in the given UTF-8 character string. More...

EXTERNRT OSUTF8CHAR *	rtxUTF8Strdup (OSCTXT pctxt, const OSUTF8CHAR utf8str)
	This function creates a duplicate copy of the given UTF-8 character string. More...

EXTERNRT OSUTF8CHAR *	rtxUTF8Strndup (OSCTXT pctxt, const OSUTF8CHAR utf8str, size_t nbytes)
	This function creates a duplicate copy of the given UTF-8 character string. More...

EXTERNRT OSUTF8CHAR *	rtxUTF8StrRefOrDup (OSCTXT pctxt, const OSUTF8CHAR utf8str)
	This function check to see if the given UTF8 string pointer exists on the memory heap. More...

EXTERNRT OSBOOL	rtxUTF8StrEqual (const OSUTF8CHAR utf8str1, const OSUTF8CHAR utf8str2)
	This function compares two UTF-8 string values for equality. More...

EXTERNRT OSBOOL	rtxUTF8StrnEqual (const OSUTF8CHAR utf8str1, const OSUTF8CHAR utf8str2, size_t count)
	This function compares two UTF-8 string values for equality. More...

EXTERNRT int	rtxUTF8Strcmp (const OSUTF8CHAR utf8str1, const OSUTF8CHAR utf8str2)
	This function compares two UTF-8 character strings and returns a trinary result (equal, less than, greater than). More...

EXTERNRT int	rtxUTF8Strncmp (const OSUTF8CHAR utf8str1, const OSUTF8CHAR utf8str2, size_t count)
	This function compares two UTF-8 character strings and returns a trinary result (equal, less than, greater than). More...

EXTERNRT OSUTF8CHAR *	rtxUTF8Strcpy (OSUTF8CHAR dest, size_t bufsiz, const OSUTF8CHAR src)
	This function copies a null-terminated UTF-8 string to a target buffer. More...

EXTERNRT OSUTF8CHAR *	rtxUTF8Strncpy (OSUTF8CHAR dest, size_t bufsiz, const OSUTF8CHAR src, size_t nchars)
	This function copies the given number of characters from a UTF-8 string to a target buffer. More...

EXTERNRT OSUINT32	rtxUTF8StrHash (const OSUTF8CHAR *str)
	This function computes a hash code for the given string value. More...

EXTERNRT const OSUTF8CHAR *	rtxUTF8StrJoin (OSCTXT pctxt, const OSUTF8CHAR str1, const OSUTF8CHAR str2, const OSUTF8CHAR str3, const OSUTF8CHAR str4, const OSUTF8CHAR str5)
	This function concatanates up to five substrings together into a single string. More...

EXTERNRT int	rtxUTF8StrToBool (const OSUTF8CHAR utf8str, OSBOOL pvalue)
	This function converts the given null-terminated UTF-8 string to a boolean (true/false) value. More...

EXTERNRT int	rtxUTF8StrnToBool (const OSUTF8CHAR utf8str, size_t nbytes, OSBOOL pvalue)
	This function converts the given part of UTF-8 string to a boolean (true/false) value. More...

EXTERNRT int	rtxUTF8StrToDouble (const OSUTF8CHAR utf8str, OSREAL pvalue)
	This function converts the given null-terminated UTF-8 string to a floating point (C/C++ double) value. More...

EXTERNRT int	rtxUTF8StrnToDouble (const OSUTF8CHAR utf8str, size_t nbytes, OSREAL pvalue)
	This function converts the given part of UTF-8 string to a double value. More...

EXTERNRT int	rtxUTF8StrToInt (const OSUTF8CHAR utf8str, OSINT32 pvalue)
	This function converts the given null-terminated UTF-8 string to an integer value. More...

EXTERNRT int	rtxUTF8StrnToInt (const OSUTF8CHAR utf8str, size_t nbytes, OSINT32 pvalue)
	This function converts the given part of UTF-8 string to an integer value. More...

EXTERNRT int	rtxUTF8StrToUInt (const OSUTF8CHAR utf8str, OSUINT32 pvalue)
	This function converts the given null-terminated UTF-8 string to an unsigned integer value. More...

EXTERNRT int	rtxUTF8StrnToUInt (const OSUTF8CHAR utf8str, size_t nbytes, OSUINT32 pvalue)
	This function converts the given part of UTF-8 string to an unsigned integer value. More...

EXTERNRT int	rtxUTF8StrToSize (const OSUTF8CHAR utf8str, size_t pvalue)
	This function converts the given null-terminated UTF-8 string to a size value (type size_t). More...

EXTERNRT int	rtxUTF8StrnToSize (const OSUTF8CHAR utf8str, size_t nbytes, size_t pvalue)
	This function converts the given part of UTF-8 string to a size value (type size_t). More...

EXTERNRT int	rtxUTF8StrToInt64 (const OSUTF8CHAR utf8str, OSINT64 pvalue)
	This function converts the given null-terminated UTF-8 string to a 64-bit integer value. More...

EXTERNRT int	rtxUTF8StrnToInt64 (const OSUTF8CHAR utf8str, size_t nbytes, OSINT64 pvalue)
	This function converts the given part of UTF-8 string to a 64-bit integer value. More...

EXTERNRT int	rtxUTF8StrToUInt64 (const OSUTF8CHAR utf8str, OSUINT64 pvalue)
	This function converts the given null-terminated UTF-8 string to an unsigned 64-bit integer value. More...

EXTERNRT int	rtxUTF8StrnToUInt64 (const OSUTF8CHAR utf8str, size_t nbytes, OSUINT64 pvalue)
	This function converts the given part of UTF-8 string to an unsigned 64-bit integer value. More...

EXTERNRT int	rtxUTF8ToDynUniStr (OSCTXT pctxt, const OSUTF8CHAR utf8str, const OSUNICHAR *ppdata, OSUINT32 pnchars)
	This function converts the given UTF-8 string to a Unicode string (UTF-16). More...

EXTERNRT int	rtxUTF8ToDynUniStr32 (OSCTXT pctxt, const OSUTF8CHAR utf8str, const OS32BITCHAR *ppdata, OSUINT32 pnchars)
	This function converts the given UTF-8 string to a Unicode string (UTF-32). More...

EXTERNRT int	rtxUTF8RemoveWhiteSpace (const OSUTF8CHAR utf8instr, size_t nbytes, const OSUTF8CHAR *putf8outstr)
	This function removes leading and trailing whitespace from a string. More...

EXTERNRT int	rtxUTF8StrToDynHexStr (OSCTXT pctxt, const OSUTF8CHAR utf8str, OSDynOctStr *pvalue)
	This function converts the given null-terminated UTF-8 string to a octet string value. More...

EXTERNRT int	rtxUTF8StrnToDynHexStr (OSCTXT pctxt, const OSUTF8CHAR utf8str, size_t nbytes, OSDynOctStr *pvalue)
	This function converts the given part of UTF-8 string to a octet string value. More...

EXTERNRT int	rtxUTF8StrToNamedBits (OSCTXT pctxt, const OSUTF8CHAR utf8str, const OSBitMapItem pBitMap, OSOCTET pvalue, OSUINT32 *pnbits, OSUINT32 bufsize)
	This function converts the given null-terminated UTF-8 string to named bit items. More...

EXTERNRT const OSUTF8CHAR *	rtxUTF8StrNextTok (OSUTF8CHAR utf8str, OSUTF8CHAR *ppNext)
	This function returns the next whitespace-separated token from the input string. More...

Detailed Description

The UTF-8 string functions handle string operations on UTF-8 encoded strings.

This is the default character string data type used for encoded XML data. UTF-8 strings are represented in C as strings of unsigned characters (bytes) to cover the full range of possible single character encodings.

Macro Definition Documentation

◆ RTUTF8STRCMPL

#define RTUTF8STRCMPL	(	name,
		lstr
	)	rtxUTF8Strcmp(name,(const OSUTF8CHAR*)lstr)

Compare UTF-8 string to a string literal.

Parameters

name	UTF-8 string variable.
lstr	C string literal value (quoted contant such as "a")

Definition at line 567 of file rtxUTF8.h.

Function Documentation

◆ rtxUTF8CharSize()

EXTERNRT int rtxUTF8CharSize ( OS32BITCHAR wc )

This function will return the number of bytes needed to encode the given 32-bit universal character value as a UTF-8 character.

Parameters

wc	32-bit wide character value.

Returns: Number of bytes needed to encode as UTF-8.

◆ rtxUTF8CharToWC()

EXTERNRT OS32BITCHAR rtxUTF8CharToWC	(	const OSUTF8CHAR *	buf,
		OSUINT32 *	len
	)

Thia function will convert a UTF-8 encoded character value into a wide character.

Parameters

buf	Pointer to UTF-8 character value.
len	Pointer to integer to receive decoded size (in bytes) of the UTF-8 character value sequence.

Returns: Converted wide character value.

◆ rtxUTF8DecodeChar()

EXTERNRT int rtxUTF8DecodeChar	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	pinbuf,
		int *	pInsize
	)

This function will convert an encoded UTF-8 character byte string into a wide character value.

Parameters

pctxt	A pointer to a context structure.
pinbuf	Pointer to UTF-8 byte sequence to be decoded.
pInsize	Number of bytes that were consumed (i.e. size of the character).

Returns: 32-bit wide character value.

◆ rtxUTF8EncodeChar()

EXTERNRT int rtxUTF8EncodeChar	(	OS32BITCHAR	wc,
		OSOCTET *	buf,
		size_t	bufsiz
	)

This function will convert a wide character into an encoded UTF-8 character byte string.

Parameters

wc	32-bit wide character value.
buf	Buffer to receive encoded UTF-8 character value.
bufsiz	Size of the buffer ot receive the encoded value.

Returns: Number of bytes consumed to encode character or negative status code if error.

◆ rtxUTF8Len()

EXTERNRT size_t rtxUTF8Len ( const OSUTF8CHAR * inbuf )

This function will return the length (in characters) of a null-terminated UTF-8 encoded string.

Parameters

inbuf A pointer to the null-terminated UTF-8 encoded string.

Returns: Number of characters in string. Note that this may be different than the number of bytes as UTF-8 characters can span multiple-bytes.

◆ rtxUTF8LenBytes()

EXTERNRT size_t rtxUTF8LenBytes ( const OSUTF8CHAR * inbuf )

This function will return the length (in bytes) of a null-terminated UTF-8 encoded string.

Parameters

inbuf A pointer to the null-terminated UTF-8 encoded string.

Returns: Number of bytes in the string.

◆ rtxUTF8RemoveWhiteSpace()

EXTERNRT int rtxUTF8RemoveWhiteSpace	(	const OSUTF8CHAR *	utf8instr,
		size_t	nbytes,
		const OSUTF8CHAR **	putf8outstr
	)

This function removes leading and trailing whitespace from a string.

Parameters

utf8instr	Input UTF-8 string from which to removed whitespace.
nbytes	Size in bytes of utf8instr.
putf8outstr	Pointer to receive result string.

Returns: Positive value = length of result string, negative value = error code.

◆ rtxUTF8StrChr()

EXTERNRT OSUTF8CHAR* rtxUTF8StrChr	(	OSUTF8CHAR *	utf8str,
		OS32BITCHAR	utf8char
	)

This function finds a character in the given UTF-8 character string.

It is similar to the C strchr function.

Parameters

utf8str	Null-terminated UTF-8 string to be searched.
utf8char	32-bit Unicode character to find.

Returns: Pointer to to the first occurrence of character in string, or NULL if character is not found.

◆ rtxUTF8Strcmp()

EXTERNRT int rtxUTF8Strcmp	(	const OSUTF8CHAR *	utf8str1,
		const OSUTF8CHAR *	utf8str2
	)

This function compares two UTF-8 character strings and returns a trinary result (equal, less than, greater than).

It is similar to the C strcmp function.

Parameters

utf8str1	UTF-8 string to be compared.
utf8str2	UTF-8 string to be compared.

Returns: -1 if utf8str1 is less than utf8str2, 0 if the two string are equal, and +1 if the utf8str1 is greater than utf8str2.

◆ rtxUTF8Strcpy()

EXTERNRT OSUTF8CHAR* rtxUTF8Strcpy	(	OSUTF8CHAR *	dest,
		size_t	bufsiz,
		const OSUTF8CHAR *	src
	)

This function copies a null-terminated UTF-8 string to a target buffer.

It is similar to the C strcpy function except more secure because it checks for buffer overrun.

Parameters

dest	Pointer to destination buffer to receive string.
bufsiz	Size of the destination buffer.
src	Pointer to null-terminated string to copy.

Returns: Pointer to destination buffer or NULL if copy failed.

◆ rtxUTF8Strdup()

EXTERNRT OSUTF8CHAR* rtxUTF8Strdup	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str
	)

This function creates a duplicate copy of the given UTF-8 character string.

It is similar to the C strdup function. Memory for the duplicated string is allocated using the rtxMemAlloc function.

Parameters

pctxt	A pointer to a context structure.
utf8str	Null-terminated UTF-8 string to be duplicated.

Returns: Pointer to duplicated string value.

◆ rtxUTF8StrEqual()

EXTERNRT OSBOOL rtxUTF8StrEqual	(	const OSUTF8CHAR *	utf8str1,
		const OSUTF8CHAR *	utf8str2
	)

This function compares two UTF-8 string values for equality.

Parameters

utf8str1	UTF-8 string to be compared.
utf8str2	UTF-8 string to be compared.

Returns: TRUE if equal, FALSE if not.

◆ rtxUTF8StrHash()

EXTERNRT OSUINT32 rtxUTF8StrHash ( const OSUTF8CHAR * str )

This function computes a hash code for the given string value.

Parameters

str	Pointer to string.

Returns: Hash code value.

◆ rtxUTF8StrJoin()

EXTERNRT const OSUTF8CHAR* rtxUTF8StrJoin	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	str1,
		const OSUTF8CHAR *	str2,
		const OSUTF8CHAR *	str3,
		const OSUTF8CHAR *	str4,
		const OSUTF8CHAR *	str5
	)

This function concatanates up to five substrings together into a single string.

Parameters

pctxt	Pointer to a context block structure.
str1	Pointer to substring to join.
str2	Pointer to substring to join.
str3	Pointer to substring to join.
str4	Pointer to substring to join.
str5	Pointer to substring to join.

Returns: Composite string consisting of all parts. Memory is allocated for this string using rtxMemAlloc and must be freed using either rtxMemFreePtr or rtxMemFree. If memory allocation for the string fails, NULL is returned.

◆ rtxUTF8Strncmp()

EXTERNRT int rtxUTF8Strncmp	(	const OSUTF8CHAR *	utf8str1,
		const OSUTF8CHAR *	utf8str2,
		size_t	count
	)

This function compares two UTF-8 character strings and returns a trinary result (equal, less than, greater than).

In this case, a maximum count of the number of bytes to compare can be specified. It is similar to the C strncmp function.

Parameters

utf8str1	UTF-8 string to be compared.
utf8str2	UTF-8 string to be compared.
count	Number of bytes to compare.

Returns: -1 if utf8str1 is less than utf8str2, 0 if the two string are equal, and +1 if the utf8str1 is greater than utf8str2.

◆ rtxUTF8Strncpy()

EXTERNRT OSUTF8CHAR* rtxUTF8Strncpy	(	OSUTF8CHAR *	dest,
		size_t	bufsiz,
		const OSUTF8CHAR *	src,
		size_t	nchars
	)

This function copies the given number of characters from a UTF-8 string to a target buffer.

It is similar to the C strncpy function except more secure because it checks for buffer overrun and ensures a null-terminator is copied to the end of the target buffer

Parameters

dest	Pointer to destination buffer to receive string.
bufsiz	Size of the destination buffer.
src	Pointer to null-terminated string to copy.
nchars	Number of characters to copy.

Returns: Pointer to destination buffer or NULL if copy failed.

◆ rtxUTF8Strndup()

EXTERNRT OSUTF8CHAR* rtxUTF8Strndup	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str,
		size_t	nbytes
	)

This function creates a duplicate copy of the given UTF-8 character string.

It is similar to the rtxUTF8Strdup function except that it allows the number of bytes to convert to be specified. Memory for the duplicated string is allocated using the rtxMemAlloc function.

Parameters

pctxt	A pointer to a context structure.
utf8str	UTF-8 string to be duplicated.
nbytes	Number of bytes from `utf8str` to duplicate.

Returns: Pointer to duplicated string value.

◆ rtxUTF8StrnEqual()

EXTERNRT OSBOOL rtxUTF8StrnEqual	(	const OSUTF8CHAR *	utf8str1,
		const OSUTF8CHAR *	utf8str2,
		size_t	count
	)

This function compares two UTF-8 string values for equality.

It is similar to the rtxUTF8StrEqual function except that it allows the number of bytes to compare to be specified.

Parameters

utf8str1	UTF-8 string to be compared.
utf8str2	UTF-8 string to be compared.
count	Number of bytes to compare.

Returns: TRUE if equal, FALSE if not.

◆ rtxUTF8StrNextTok()

EXTERNRT const OSUTF8CHAR* rtxUTF8StrNextTok	(	OSUTF8CHAR *	utf8str,
		OSUTF8CHAR **	ppNext
	)

This function returns the next whitespace-separated token from the input string.

It also returns a pointer to the first non-whitespace chracter after the parsed token. Note that the input string is altered in the operation as null-terminators are insterted to mark the token boundaries.

Parameters

utf8str	Null-terminated UTF-8 string to parse. This string will be altered. Use rtxUTF8Strdup to make a copy of original string before calling this function if the original string cannot be altered.
ppNext	Pointer to receive next location in string after parsed token. This can be used as input to get the next token. If NULL returned, all tokens in in the string have been parsed.

Returns: Pointer to next parsed token. NULL if no more tokens.

◆ rtxUTF8StrnToBool()

EXTERNRT int rtxUTF8StrnToBool	(	const OSUTF8CHAR *	utf8str,
		size_t	nbytes,
		OSBOOL *	pvalue
	)

This function converts the given part of UTF-8 string to a boolean (true/false) value.

It is assumed the string contains only the tokens 'true', 'false', '1', or '0'.

Parameters

utf8str	Null-terminated UTF-8 string to convert
nbytes	Size in bytes of utf8Str.
pvalue	Pointer to boolean value to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrnToDouble()

EXTERNRT int rtxUTF8StrnToDouble	(	const OSUTF8CHAR *	utf8str,
		size_t	nbytes,
		OSREAL *	pvalue
	)

This function converts the given part of UTF-8 string to a double value.

It is assumed the string contains only numeric digits, whitespace, and other special floating point characters. It is similar to the C atof function except that the result is returned as a separate argument and an error status value is returned if the conversion cannot be performed successfully.

Parameters

utf8str	UTF-8 string to convert. Not necessary to be null-terminated.
nbytes	Size in bytes of utf8Str.
pvalue	Pointer to double to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrnToDynHexStr()

EXTERNRT int rtxUTF8StrnToDynHexStr	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str,
		size_t	nbytes,
		OSDynOctStr *	pvalue
	)

This function converts the given part of UTF-8 string to a octet string value.

The string consists of a series of hex digits. This is the dynamic version in which memory is allocated for the returned octet string variable.

Parameters

pctxt	Pointer to context block structure.
utf8str	Null-terminated UTF-8 string to convert
nbytes	Size in bytes of utf8Str.
pvalue	Pointer to a variable to receive the decoded octet string value.

Returns

Completion status of operation:

0 = success,
negative return value is error.

◆ rtxUTF8StrnToInt()

EXTERNRT int rtxUTF8StrnToInt	(	const OSUTF8CHAR *	utf8str,
		size_t	nbytes,
		OSINT32 *	pvalue
	)

This function converts the given part of UTF-8 string to an integer value.

It is assumed the string contains only numeric digits and whitespace. It is similar to the C atoi function except that the result is returned as a separate argument and an error status value is returned if the conversion cannot be performed successfully.

Parameters

utf8str	UTF-8 string to convert. Not necessary to be null-terminated.
nbytes	Size in bytes of utf8Str.
pvalue	Pointer to integer to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrnToInt64()

EXTERNRT int rtxUTF8StrnToInt64	(	const OSUTF8CHAR *	utf8str,
		size_t	nbytes,
		OSINT64 *	pvalue
	)

This function converts the given part of UTF-8 string to a 64-bit integer value.

It is assumed the string contains only numeric digits and whitespace.

Parameters

utf8str	UTF-8 string to convert. Not necessary to be null-terminated.
nbytes	Size in bytes of utf8Str.
pvalue	Pointer to integer to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrnToSize()

EXTERNRT int rtxUTF8StrnToSize	(	const OSUTF8CHAR *	utf8str,
		size_t	nbytes,
		size_t *	pvalue
	)

This function converts the given part of UTF-8 string to a size value (type size_t).

It is assumed the string contains only numeric digits and whitespace.

Parameters

utf8str	UTF-8 string to convert. Not necessary to be null-terminated.
nbytes	Size in bytes of utf8Str.
pvalue	Pointer to size_t value to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrnToUInt()

EXTERNRT int rtxUTF8StrnToUInt	(	const OSUTF8CHAR *	utf8str,
		size_t	nbytes,
		OSUINT32 *	pvalue
	)

This function converts the given part of UTF-8 string to an unsigned integer value.

It is assumed the string contains only numeric digits and whitespace.

Parameters

utf8str	UTF-8 string to convert. Not necessary to be null-terminated.
nbytes	Size in bytes of utf8Str.
pvalue	Pointer to integer to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrnToUInt64()

EXTERNRT int rtxUTF8StrnToUInt64	(	const OSUTF8CHAR *	utf8str,
		size_t	nbytes,
		OSUINT64 *	pvalue
	)

This function converts the given part of UTF-8 string to an unsigned 64-bit integer value.

It is assumed the string contains only numeric digits and whitespace.

Parameters

utf8str	UTF-8 string to convert. Not necessary to be null-terminated.
nbytes	Size in bytes of utf8Str.
pvalue	Pointer to integer to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrRefOrDup()

EXTERNRT OSUTF8CHAR* rtxUTF8StrRefOrDup	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str
	)

This function check to see if the given UTF8 string pointer exists on the memory heap.

If it does, its reference count is incremented; otherwise, a duplicate copy is made.

Parameters

pctxt	A pointer to a context structure.
utf8str	Null-terminated UTF-8 string variable.

Returns: Pointer to string value. This will either be the existing UTF-8 string pointer value (utf8str) or a new value.

◆ rtxUTF8StrToBool()

EXTERNRT int rtxUTF8StrToBool	(	const OSUTF8CHAR *	utf8str,
		OSBOOL *	pvalue
	)

This function converts the given null-terminated UTF-8 string to a boolean (true/false) value.

It is assumed the string contains only the tokens 'true', 'false', '1', or '0'.

Parameters

utf8str	Null-terminated UTF-8 string to convert
pvalue	Pointer to boolean value to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrToDouble()

EXTERNRT int rtxUTF8StrToDouble	(	const OSUTF8CHAR *	utf8str,
		OSREAL *	pvalue
	)

This function converts the given null-terminated UTF-8 string to a floating point (C/C++ double) value.

It is assumed the string contains only numeric digits, special floating point characters (+,-,E,.), and whitespace. It is similar to the C atof function except that the result is returned as a separate argument and an error status value is returned if the conversion cannot be performed successfully.

Parameters

utf8str	Null-terminated UTF-8 string to convert
pvalue	Pointer to double to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrToDynHexStr()

EXTERNRT int rtxUTF8StrToDynHexStr	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str,
		OSDynOctStr *	pvalue
	)

This function converts the given null-terminated UTF-8 string to a octet string value.

The string consists of a series of hex digits. This is the dynamic version in which memory is allocated for the returned octet string variable.

Parameters

pctxt	Pointer to context block structure.
utf8str	Null-terminated UTF-8 string to convert
pvalue	Pointer to a variable to receive the decoded octet string value.

Returns

Completion status of operation:

0 = success,
negative return value is error.

◆ rtxUTF8StrToInt()

EXTERNRT int rtxUTF8StrToInt	(	const OSUTF8CHAR *	utf8str,
		OSINT32 *	pvalue
	)

This function converts the given null-terminated UTF-8 string to an integer value.

It is assumed the string contains only numeric digits and whitespace. It is similar to the C atoi function except that the result is returned as a separate argument and an error status value is returned if the conversion cannot be performed successfully.

Parameters

utf8str	Null-terminated UTF-8 string to convert
pvalue	Pointer to integer to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrToInt64()

EXTERNRT int rtxUTF8StrToInt64	(	const OSUTF8CHAR *	utf8str,
		OSINT64 *	pvalue
	)

This function converts the given null-terminated UTF-8 string to a 64-bit integer value.

It is assumed the string contains only numeric digits and whitespace.

Parameters

utf8str	Null-terminated UTF-8 string to convert
pvalue	Pointer to integer to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrToNamedBits()

EXTERNRT int rtxUTF8StrToNamedBits	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str,
		const OSBitMapItem *	pBitMap,
		OSOCTET *	pvalue,
		OSUINT32 *	pnbits,
		OSUINT32	bufsize
	)

This function converts the given null-terminated UTF-8 string to named bit items.

The token-to-bit mappings are defined by a bit map table that is passed into the function. It is assumed the string contains a space-separated list of named bit token values.

Parameters

pctxt	Context structure
utf8str	Null-terminated UTF-8 string to convert
pBitMap	Bit map defining bit to otken mappings
pvalue	Pointer to byte array to receive result.
pnbits	Pointer to integer to received number of bits.
bufsize	Size of byte array to received decoded bits.

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrToSize()

EXTERNRT int rtxUTF8StrToSize	(	const OSUTF8CHAR *	utf8str,
		size_t *	pvalue
	)

This function converts the given null-terminated UTF-8 string to a size value (type size_t).

It is assumed the string contains only numeric digits and whitespace.

Parameters

utf8str	Null-terminated UTF-8 string to convert
pvalue	Pointer to size_t value to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrToUInt()

EXTERNRT int rtxUTF8StrToUInt	(	const OSUTF8CHAR *	utf8str,
		OSUINT32 *	pvalue
	)

This function converts the given null-terminated UTF-8 string to an unsigned integer value.

It is assumed the string contains only numeric digits and whitespace.

Parameters

utf8str	Null-terminated UTF-8 string to convert
pvalue	Pointer to integer to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8StrToUInt64()

EXTERNRT int rtxUTF8StrToUInt64	(	const OSUTF8CHAR *	utf8str,
		OSUINT64 *	pvalue
	)

This function converts the given null-terminated UTF-8 string to an unsigned 64-bit integer value.

It is assumed the string contains only numeric digits and whitespace.

Parameters

utf8str	Null-terminated UTF-8 string to convert
pvalue	Pointer to integer to receive result

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8ToDynUniStr()

EXTERNRT int rtxUTF8ToDynUniStr	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str,
		const OSUNICHAR **	ppdata,
		OSUINT32 *	pnchars
	)

This function converts the given UTF-8 string to a Unicode string (UTF-16).

Memory is allocated for the Unicode string using the rtxMemAlloc function. This memory will be freed when the context is freed (rtxFreeContext) or it can be freed using rtxMemFreePtr.

Parameters

pctxt	A pointer to a context structure.
utf8str	UTF-8 string to convert, null-terminated.
ppdata	Pointer to pointer to receive output string.
pnchars	Pointer to integer to receive number of chars (the size of *ppdata array).

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8ToDynUniStr32()

EXTERNRT int rtxUTF8ToDynUniStr32	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str,
		const OS32BITCHAR **	ppdata,
		OSUINT32 *	pnchars
	)

This function converts the given UTF-8 string to a Unicode string (UTF-32).

Memory is allocated for the Unicode string using the rtxMemAlloc function. This memory will be freed when the context is freed (rtxFreeContext) or it can be freed using rtxMemFreePtr.

Parameters

pctxt	A pointer to a context structure.
utf8str	UTF-8 string to convert, null-terminated.
ppdata	Pointer to pointer to receive output string.
pnchars	Pointer to integer to receive number of chars (the size of *ppdata array).

Returns: Status: 0 = OK, negative value = error

◆ rtxUTF8ToUnicode()

EXTERNRT long rtxUTF8ToUnicode	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	inbuf,
		OSUNICHAR *	outbuf,
		size_t	outbufsiz
	)

This function converts a UTF-8 string to a Unicode string (UTF-16).

The Unicode string is stored as an array of 16-bit characters (unsigned short integers).

Parameters

pctxt	A pointer to a context structure.
inbuf	UTF-8 string to convert.
outbuf	Output buffer to receive converted Unicode data.
outbufsiz	Size of the output buffer in bytes.

Returns

Completion status of operation:

number of Unicode characters in the string
negative return value is error.

◆ rtxUTF8ToUnicode32()

EXTERNRT long rtxUTF8ToUnicode32	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	inbuf,
		OS32BITCHAR *	outbuf,
		size_t	outbufsiz
	)

This function converts a UTF-8 string to a Unicode string (UTF-32).

The Unicode string is stored as an array of 32-bit characters (unsigned integers).

Parameters

pctxt	A pointer to a context structure.
inbuf	UTF-8 string to convert.
outbuf	Output buffer to receive converted Unicode data.
outbufsiz	Size of the output buffer in bytes.

Returns

Completion status of operation:

number of Unicode characters in the string
negative return value is error.

◆ rtxValidateUTF8()

EXTERNRT int rtxValidateUTF8	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	inbuf
	)

This function will validate a UTF-8 encoded string to ensure that it is encoded correctly.

Parameters

pctxt	A pointer to a context structure.
inbuf	A pointer to the null-terminated UTF-8 encoded string.

Returns

Completion status of operation:

0 = success,
negative return value is error.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ RTUTF8STRCMPL

Function Documentation

◆ rtxUTF8CharSize()

◆ rtxUTF8CharToWC()

◆ rtxUTF8DecodeChar()

◆ rtxUTF8EncodeChar()

◆ rtxUTF8Len()

◆ rtxUTF8LenBytes()

◆ rtxUTF8RemoveWhiteSpace()

◆ rtxUTF8StrChr()

◆ rtxUTF8Strcmp()

◆ rtxUTF8Strcpy()

◆ rtxUTF8Strdup()

◆ rtxUTF8StrEqual()

◆ rtxUTF8StrHash()

◆ rtxUTF8StrJoin()

◆ rtxUTF8Strncmp()

◆ rtxUTF8Strncpy()

◆ rtxUTF8Strndup()

◆ rtxUTF8StrnEqual()

◆ rtxUTF8StrNextTok()

◆ rtxUTF8StrnToBool()

◆ rtxUTF8StrnToDouble()

◆ rtxUTF8StrnToDynHexStr()

◆ rtxUTF8StrnToInt()

◆ rtxUTF8StrnToInt64()

◆ rtxUTF8StrnToSize()

◆ rtxUTF8StrnToUInt()

◆ rtxUTF8StrnToUInt64()

◆ rtxUTF8StrRefOrDup()

◆ rtxUTF8StrToBool()

◆ rtxUTF8StrToDouble()

◆ rtxUTF8StrToDynHexStr()

◆ rtxUTF8StrToInt()

◆ rtxUTF8StrToInt64()

◆ rtxUTF8StrToNamedBits()

◆ rtxUTF8StrToSize()

◆ rtxUTF8StrToUInt()

◆ rtxUTF8StrToUInt64()

◆ rtxUTF8ToDynUniStr()

◆ rtxUTF8ToDynUniStr32()

◆ rtxUTF8ToUnicode()

◆ rtxUTF8ToUnicode32()

◆ rtxValidateUTF8()