The ifx_gl_tomupper() function

The ifx_gl_tomupper() function converts a lowercase multibyte character to its uppercase equivalent.

Syntax

#include <ifxgls.h>
...
unsigned short ifx_gl_tomupper(dst_mb, src_mb, src_mb_byte_limit)
       gl_mchar_t *dst_mb;
       gl_mchar_t *src_mb;
       int src_mb_byte_limit;
dst_mb
A pointer to the destination character, which holds the case conversion for the src_mb character.
src_mb
A pointer to the source multibyte character that you want to convert to its uppercase equivalent.
src_mb_byte_limit
The integer number of bytes to read from src_mb to try to form a complete multibyte character. If src_mb_byte_limit is IFX_GL_NO_LIMIT, this function reads as many bytes as necessary from src_mb to form a complete multibyte character.
Valid in client application Valid in DataBlade® UDR
Yes Yes

Usage

The ifx_gl_tomupper() function obtains the uppercase equivalent of the src_mb source multibyte character and stores it in the dst_mb destination buffer. If the locale does not define an uppercase equivalent for src_mb, ifx_gl_tomupper() copies src_mb to dst_mb unchanged.

For a multibyte-character string, the size of the uppercase multibyte string might not equal the size of the uppercase string. Therefore, to perform case conversion on multibyte characters, you must take the following special processing steps:
  • Determine whether you need to allocate a separate destination buffer.

    If a destination buffer is needed, determine its size.

  • Determine the number of bytes that have been read and written in the case-conversion process.
The ifx_gl_tomupper() function returns an unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb. The library provides the following macros to obtain this information from the return value.
IFX_GL_CASE_CONV_SRC_BYTES()
The number of bytes read from the source string.
IFX_GL_CASE_CONV_DST_BYTES()
The number of bytes written to the destination buffer.

Return values

>0
An unsigned short integer that encodes the number of bytes read from src_mb and the number of bytes written to dst_mb.
0
The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

This function does not return a unique value to indicate an error. If an error occurred, the function returns 0 and sets the ifx_gl_lc_errno() error number to one of the following values.
IFX_GL_EILSEQ
The *src_mb value is not a valid multibyte character.
IFX_GL_EINVAL
The function cannot determine whether src_mb is a valid multibyte character because it would need to read more than src_mb_byte_limit bytes from src_mb. If src_mb_byte_limit is less than or equal to 0, this function always returns this error.