ifx_gl_mblen

ifx_gl_mblen - returns number of bytes in a multi-byte character

SYNOPSIS


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

DESCRIPTION

This function determines the number of bytes in the multi-byte character, mb.

If mb_byte_limit is IFX_GL_NO_LIMIT then this function will read as many bytes as necessary from mb to form a complete character; otherwise, it will not read more than mb_byte_limit bytes from mb when trying to form a complete character. See Multi-Byte Character Termination for more general information about mb_byte_limit.

RETURN VALUES

This function returns the number of bytes read from mb.

ERRORS

If an error has occurred, this function returns -1 and sets ifx_gl_lc_errno() to one of the following,

[IFX_GL_EILSEQ]: mb is not a valid multi-byte character
[IFX_GL_EINVAL]: The function cannot determine whether mb is a valid multi-byte 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 zero, this function always gives this error. See Keeping Multi-Byte Strings Consistent for more information about this error.

PERFORMANCE

This function is often used to advance a pointer through a null-terminated string. However, it is slightly faster to advance a pointer through a null-terminated string using ifx_gl_mbsnext(),

  for ( mb = mbs; *mb != '\0';  )
    {
    if ( (mb = ifx_gl_mbsnext(mb, IFX_GL_NO_LIMIT)) == NULL )
      /* handle error */
    }

ACKNOWLEDGEMENT

Portions of this description were derived from the X/Open CAE Specification: "System Interfaces and Headers, Issue 4"; X/Open Document Number: C202; ISBN: 1-872630-47-2; Published by X/Open Company Ltd., U.K.