The ifx_gl_tomlower() function
The ifx_gl_tomlower() function converts an uppercase multibyte character to its lowercase equivalent.
Syntax
#include <ifxgls.h>
...
unsigned short ifx_gl_tomlower(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 lowercase 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_tomlower() function obtains the lowercase equivalent of the src_mb source multibyte character and stores it in the dst_mb destination buffer. If the locale does not define a lowercase equivalent for src_mb, ifx_gl_tomlower() copies src_mb to dst_mb unchanged.
For
a multibyte-character string, the size of the lowercase 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_tomlower() 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.