UTF-8 String Functions

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

Defines

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

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).
EXTERNRT int rtxValidateUTF8 (OSCTXT *pctxt, const OSUTF8CHAR *inbuf)
 This function will validate a UTF-8 encoded string to ensure that it is encoded correctly.
EXTERNRT size_t rtxUTF8Len (const OSUTF8CHAR *inbuf)
 This function will return the length (in characters) of a null-terminated UTF-8 encoded string.
EXTERNRT size_t rtxUTF8LenBytes (const OSUTF8CHAR *inbuf)
 This function will return the length (in bytes) of a null-terminated UTF-8 encoded string.
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.
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.
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.
EXTERNRT OS32BITCHAR rtxUTF8CharToWC (const OSUTF8CHAR *buf, OSUINT32 *len)
 Thia function will convert a UTF-8 encoded character value into a wide character.
EXTERNRT OSUTF8CHAR * rtxUTF8StrChr (OSUTF8CHAR *utf8str, OS32BITCHAR utf8char)
 This function finds a character in the given UTF-8 character string.
EXTERNRT OSUTF8CHAR * rtxUTF8Strdup (OSCTXT *pctxt, const OSUTF8CHAR *utf8str)
 This function creates a duplicate copy of the given UTF-8 character string.
EXTERNRT OSUTF8CHAR * rtxUTF8Strndup (OSCTXT *pctxt, const OSUTF8CHAR *utf8str, size_t nbytes)
 This function creates a duplicate copy of the given UTF-8 character string.
EXTERNRT OSUTF8CHAR * rtxUTF8StrRefOrDup (OSCTXT *pctxt, const OSUTF8CHAR *utf8str)
 This function check to see if the given UTF8 string pointer exists on the memory heap.
EXTERNRT OSBOOL rtxUTF8StrEqual (const OSUTF8CHAR *utf8str1, const OSUTF8CHAR *utf8str2)
 This function compares two UTF-8 string values for equality.
EXTERNRT OSBOOL rtxUTF8StrnEqual (const OSUTF8CHAR *utf8str1, const OSUTF8CHAR *utf8str2, size_t count)
 This function compares two UTF-8 string values for equality.
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).
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).
EXTERNRT OSUTF8CHAR * rtxUTF8Strcpy (OSUTF8CHAR *dest, size_t bufsiz, const OSUTF8CHAR *src)
 This function copies a null-terminated UTF-8 string to a target buffer.
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.
EXTERNRT OSUINT32 rtxUTF8StrHash (const OSUTF8CHAR *str)
 This function computes a hash code for the given string value.
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.
EXTERNRT int rtxUTF8StrToBool (const OSUTF8CHAR *utf8str, OSBOOL *pvalue)
 This function converts the given null-terminated UTF-8 string to a boolean (true/false) value.
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.
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.
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.
EXTERNRT int rtxUTF8StrToInt (const OSUTF8CHAR *utf8str, OSINT32 *pvalue)
 This function converts the given null-terminated UTF-8 string to an integer value.
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.
EXTERNRT int rtxUTF8StrToUInt (const OSUTF8CHAR *utf8str, OSUINT32 *pvalue)
 This function converts the given null-terminated UTF-8 string to an unsigned integer value.
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.
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).
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).
EXTERNRT int rtxUTF8StrToInt64 (const OSUTF8CHAR *utf8str, OSINT64 *pvalue)
 This function converts the given null-terminated UTF-8 string to a 64-bit integer value.
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.
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.
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.
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.
EXTERNRT int rtxUTF8RemoveWhiteSpace (const OSUTF8CHAR *utf8instr, size_t nbytes, const OSUTF8CHAR **putf8outstr)
 This function removes leading and trailing whitespace from a string.
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.
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.
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.
EXTERNRT const OSUTF8CHAR * rtxUTF8StrNextTok (OSUTF8CHAR *utf8str, OSUTF8CHAR **ppNext)
 This function returns the next whitespace-separated token from the input string.

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.

Define Documentation

#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 531 of file rtxUTF8.h.

Function Documentation

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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
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.
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
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
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
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
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
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.
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
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
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.
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
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
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
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
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
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
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.

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 decoded.
Returns:
Status: 0 = OK, negative value = error
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.
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.