The ifx_gl_mbsnext() function

The ifx_gl_mbsnext() function returns the next multibyte character from a multibyte string.

Syntax

#include <ifxgls.h>
...
gl_mchar_t *ifx_gl_mbsnext(mb, mb_byte_limit)
        gl_mchar_t *mb;
        int mb_byte_limit;

mb: A pointer to the current multibyte character in the multibyte string.
mb_byte_limit: The integer number of bytes to read from mb to try to form a complete multibyte character. If mb_byte_limit is IFX_GL_NO_LIMIT, the function reads as many bytes as necessary from mb to form a complete character.


Valid in client application	Valid in DataBlade® UDR
Yes	Yes

Usage

The ifx_gl_mbsnext() function returns a pointer to the next multibyte character after mb in a multibyte-character string. This function is typically used to transform the single-byte forward-traversal loop to a multibyte loop. For example, suppose you have the following single-byte loop:

for ( sb = sbs; *sb != '\0'; sb++ )
    {
    /* Process single-byte character */

The following code fragment traverses the string with the ifx_gl_mbsnext() function instead of incrementing the pointer of the single-byte loop:

for ( mb = mbs; *mb != '\0'; )
    {
    /* Process multibyte character; increment pointer through string */
    if ( (mb = ifx_gl_mbsnext(mb, IFX_GL_NO_LIMIT)) == NULL )
    /* Handle error */
    }

Return values

gl_mchar_t *: A pointer to the byte that immediately follows mb.
NULL: The function was not successful, and the error number is set to indicate the cause. See the Errors section.

Errors

If an error occurred, this function returns NULL and sets the ifx_gl_lc_errno() error number to one of the following values.

IFX_GL_EILSEQ: The *mb value is not a valid multibyte character.
IFX_GL_EINVAL: The function cannot determine whether mb is a valid multibyte character because it would need to read more than mb_byte_limit bytes from mb. If mb_byte_limit is less than or equal to 0, this function always returns this error.