UTF-8 String Functions

Macros
#define	rtxUTF8StrToInt32   rtxUTF8StrToInt
#define	rtxUTF8StrToUInt32   rtxUTF8StrToUInt
#define	RTUTF8STRCMPL(name, lstr)   rtxUTF8Strcmp(name,(const OSUTF8CHAR*)lstr)
#define	OSRTCHKUTF8LEN(str, lower, upper, stat)

Functions
long	rtxUTF8ToUnicode (OSCTXT *pctxt, const OSUTF8CHAR *inbuf, OSUNICHAR *outbuf, size_t outbufsiz)
long	rtxUTF8ToUnicode32 (OSCTXT *pctxt, const OSUTF8CHAR *inbuf, OS32BITCHAR *outbuf, size_t outbufsiz)
int	rtxValidateUTF8 (OSCTXT *pctxt, const OSUTF8CHAR *inbuf)
size_t	rtxUTF8Len (const OSUTF8CHAR *inbuf)
size_t	rtxCalcUTF8Len (const OSUTF8CHAR *inbuf, size_t inbufBytes)
size_t	rtxUTF8LenBytes (const OSUTF8CHAR *inbuf)
int	rtxUTF8CharSize (OS32BITCHAR wc)
int	rtxUTF8EncodeChar (OS32BITCHAR wc, OSOCTET *buf, size_t bufsiz)
int	rtxUTF8DecodeChar (OSCTXT *pctxt, const OSUTF8CHAR *pinbuf, int *pInsize)
OS32BITCHAR	rtxUTF8CharToWC (const OSUTF8CHAR *buf, OSUINT32 *len)
OSUTF8CHAR *	rtxUTF8StrChr (OSUTF8CHAR *utf8str, OS32BITCHAR utf8char)
OSUTF8CHAR *	rtxUTF8Strdup (OSCTXT *pctxt, const OSUTF8CHAR *utf8str)
OSUTF8CHAR *	rtxUTF8Strndup (OSCTXT *pctxt, const OSUTF8CHAR *utf8str, size_t nbytes)
OSUTF8CHAR *	rtxUTF8StrRefOrDup (OSCTXT *pctxt, const OSUTF8CHAR *utf8str)
OSBOOL	rtxUTF8StrEqual (const OSUTF8CHAR *utf8str1, const OSUTF8CHAR *utf8str2)
OSBOOL	rtxUTF8StrnEqual (const OSUTF8CHAR *utf8str1, const OSUTF8CHAR *utf8str2, size_t count)
int	rtxUTF8Strcmp (const OSUTF8CHAR *utf8str1, const OSUTF8CHAR *utf8str2)
int	rtxUTF8Strncmp (const OSUTF8CHAR *utf8str1, const OSUTF8CHAR *utf8str2, size_t count)
OSUTF8CHAR *	rtxUTF8Strcpy (OSUTF8CHAR *dest, size_t bufsiz, const OSUTF8CHAR *src)
OSUTF8CHAR *	rtxUTF8Strncpy (OSUTF8CHAR *dest, size_t bufsiz, const OSUTF8CHAR *src, size_t nchars)
OSUINT32	rtxUTF8StrHash (const OSUTF8CHAR *str)
const OSUTF8CHAR *	rtxUTF8StrJoin (OSCTXT *pctxt, const OSUTF8CHAR *str1, const OSUTF8CHAR *str2, const OSUTF8CHAR *str3, const OSUTF8CHAR *str4, const OSUTF8CHAR *str5)
int	rtxUTF8StrToBool (const OSUTF8CHAR *utf8str, OSBOOL *pvalue)
int	rtxUTF8StrnToBool (const OSUTF8CHAR *utf8str, size_t nbytes, OSBOOL *pvalue)
int	rtxUTF8StrToDouble (const OSUTF8CHAR *utf8str, OSREAL *pvalue)
int	rtxUTF8StrnToDouble (const OSUTF8CHAR *utf8str, size_t nbytes, OSREAL *pvalue)
int	rtxUTF8StrToInt (const OSUTF8CHAR *utf8str, OSINT32 *pvalue)
int	rtxUTF8StrnToInt (const OSUTF8CHAR *utf8str, size_t nbytes, OSINT32 *pvalue)
int	rtxUTF8StrToUInt (const OSUTF8CHAR *utf8str, OSUINT32 *pvalue)
int	rtxUTF8StrnToUInt (const OSUTF8CHAR *utf8str, size_t nbytes, OSUINT32 *pvalue)
int	rtxUTF8StrToSize (const OSUTF8CHAR *utf8str, size_t *pvalue)
int	rtxUTF8StrnToSize (const OSUTF8CHAR *utf8str, size_t nbytes, size_t *pvalue)
int	rtxUTF8StrToInt64 (const OSUTF8CHAR *utf8str, OSINT64 *pvalue)
int	rtxUTF8StrnToInt64 (const OSUTF8CHAR *utf8str, size_t nbytes, OSINT64 *pvalue)
int	rtxUTF8StrToUInt64 (const OSUTF8CHAR *utf8str, OSUINT64 *pvalue)
int	rtxUTF8StrnToUInt64 (const OSUTF8CHAR *utf8str, size_t nbytes, OSUINT64 *pvalue)
int	rtxUTF8ToDynUniStr (OSCTXT *pctxt, const OSUTF8CHAR *utf8str, const OSUNICHAR **ppdata, OSUINT32 *pnchars)
int	rtxUTF8ToDynUniStr32 (OSCTXT *pctxt, const OSUTF8CHAR *utf8str, const OS32BITCHAR **ppdata, OSUINT32 *pnchars)
int	rtxUTF8RemoveWhiteSpace (const OSUTF8CHAR *utf8instr, size_t nbytes, const OSUTF8CHAR **putf8outstr)
int	rtxUTF8StrToDynHexStr (OSCTXT *pctxt, const OSUTF8CHAR *utf8str, OSDynOctStr *pvalue)
int	rtxUTF8StrnToDynHexStr (OSCTXT *pctxt, const OSUTF8CHAR *utf8str, size_t nbytes, OSDynOctStr *pvalue)
int	rtxUTF8StrToNamedBits (OSCTXT *pctxt, const OSUTF8CHAR *utf8str, const OSBitMapItem *pBitMap, OSOCTET *pvalue, OSUINT32 *pnbits, OSUINT32 bufsize)
const OSUTF8CHAR *	rtxUTF8StrNextTok (OSUTF8CHAR *utf8str, OSUTF8CHAR **ppNext)

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

OSRTCHKUTF8LEN

#define OSRTCHKUTF8LEN	(		str,
			lower,
			upper,
			stat
	)

Value:

do { size_t nchars = rtxUTF8Len (str); \
stat = (nchars >= lower && nchars <= upper) ? 0 : RTERR_CONSVIO; } while(0)

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")

Function Documentation

rtxUTF8CharSize()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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.