XBinder  Version 2.9.x
Macros | Functions
UTF-8 String Functions

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
nameUTF-8 string variable.
lstrC 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
wc32-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
bufPointer to UTF-8 character value.
lenPointer 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
pctxtA pointer to a context structure.
pinbufPointer to UTF-8 byte sequence to be decoded.
pInsizeNumber 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
wc32-bit wide character value.
bufBuffer to receive encoded UTF-8 character value.
bufsizSize 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
inbufA 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
inbufA 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
utf8instrInput UTF-8 string from which to removed whitespace.
nbytesSize in bytes of utf8instr.
putf8outstrPointer 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
utf8strNull-terminated UTF-8 string to be searched.
utf8char32-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
utf8str1UTF-8 string to be compared.
utf8str2UTF-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
destPointer to destination buffer to receive string.
bufsizSize of the destination buffer.
srcPointer 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
pctxtA pointer to a context structure.
utf8strNull-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
utf8str1UTF-8 string to be compared.
utf8str2UTF-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
strPointer 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
pctxtPointer to a context block structure.
str1Pointer to substring to join.
str2Pointer to substring to join.
str3Pointer to substring to join.
str4Pointer to substring to join.
str5Pointer 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
utf8str1UTF-8 string to be compared.
utf8str2UTF-8 string to be compared.
countNumber 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
destPointer to destination buffer to receive string.
bufsizSize of the destination buffer.
srcPointer to null-terminated string to copy.
ncharsNumber 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
pctxtA pointer to a context structure.
utf8strUTF-8 string to be duplicated.
nbytesNumber 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
utf8str1UTF-8 string to be compared.
utf8str2UTF-8 string to be compared.
countNumber 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
utf8strNull-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.
ppNextPointer 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
utf8strNull-terminated UTF-8 string to convert
nbytesSize in bytes of utf8Str.
pvaluePointer 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
utf8strUTF-8 string to convert. Not necessary to be null-terminated.
nbytesSize in bytes of utf8Str.
pvaluePointer 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
pctxtPointer to context block structure.
utf8strNull-terminated UTF-8 string to convert
nbytesSize in bytes of utf8Str.
pvaluePointer 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
utf8strUTF-8 string to convert. Not necessary to be null-terminated.
nbytesSize in bytes of utf8Str.
pvaluePointer 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
utf8strUTF-8 string to convert. Not necessary to be null-terminated.
nbytesSize in bytes of utf8Str.
pvaluePointer 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
utf8strUTF-8 string to convert. Not necessary to be null-terminated.
nbytesSize in bytes of utf8Str.
pvaluePointer 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
utf8strUTF-8 string to convert. Not necessary to be null-terminated.
nbytesSize in bytes of utf8Str.
pvaluePointer 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
utf8strUTF-8 string to convert. Not necessary to be null-terminated.
nbytesSize in bytes of utf8Str.
pvaluePointer 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
pctxtA pointer to a context structure.
utf8strNull-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
utf8strNull-terminated UTF-8 string to convert
pvaluePointer 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
utf8strNull-terminated UTF-8 string to convert
pvaluePointer 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
pctxtPointer to context block structure.
utf8strNull-terminated UTF-8 string to convert
pvaluePointer 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
utf8strNull-terminated UTF-8 string to convert
pvaluePointer 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
utf8strNull-terminated UTF-8 string to convert
pvaluePointer 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
pctxtContext structure
utf8strNull-terminated UTF-8 string to convert
pBitMapBit map defining bit to otken mappings
pvaluePointer to byte array to receive result.
pnbitsPointer to integer to received number of bits.
bufsizeSize 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
utf8strNull-terminated UTF-8 string to convert
pvaluePointer 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
utf8strNull-terminated UTF-8 string to convert
pvaluePointer 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
utf8strNull-terminated UTF-8 string to convert
pvaluePointer 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
pctxtA pointer to a context structure.
utf8strUTF-8 string to convert, null-terminated.
ppdataPointer to pointer to receive output string.
pncharsPointer 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
pctxtA pointer to a context structure.
utf8strUTF-8 string to convert, null-terminated.
ppdataPointer to pointer to receive output string.
pncharsPointer 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
pctxtA pointer to a context structure.
inbufUTF-8 string to convert.
outbufOutput buffer to receive converted Unicode data.
outbufsizSize 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
pctxtA pointer to a context structure.
inbufUTF-8 string to convert.
outbufOutput buffer to receive converted Unicode data.
outbufsizSize 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
pctxtA pointer to a context structure.
inbufA pointer to the null-terminated UTF-8 encoded string.
Returns
Completion status of operation:
  • 0 = success,
  • negative return value is error.