GLS Library Macros

SYNOPSIS

#include <ifxgls.h>

DESCRIPTION

IFX_GL_MB_MAX
The maximum number of bytes that any multi-byte character in any locale can occupy. This macro is usually used to allocate space in static buffers which are intended to contain one or more multi-byte characters; for example,
  gl_mchar_t one_mb_character[IFX_GL_MB_MAX];

  gl_mchar_t null_terminated_mb_character_string[20*IFX_GL_MB_MAX+1];
IFX_GL_IS_SINGLE_BYTE
If the current locale uses a single-byte codeset, this macro returns 1; else it returns 0. Therefore, if this macro returns 1, then you can assume that one character occupies one byte; for example,
  if ( IFX_GL_IS_SINGLE_BYTE )
    /* Do processing optimized for single-byte */
  else
    /* Do multi-byte processing */
While this allows you to create an optimized version of your code for single-byte character processing; it does create two code paths that you must maintain. All the GLS library functions that process multi-byte characters use this function internally to optimize themselves; therefore, you will only find the need to use this macro in highly performance-sensitive code, if ever.
IFX_GL_IS_CODESET_ORDER
If the current locale uses character codepoint values to compare characters, this macro returns 1; else it returns 0. Therefore, if this macro returns 1, then you can assume that two strings can be compared by using functions like strcmp(); for example,
  if ( IFX_GL_IS_CODESET_ORDER )
    /* Do comparison optimized for codeset order */
  else
    /* Do non-codeset order comparison */
While this allows you to create an optimized version of your code for codeset-order comparisons; it does create two code paths that you must maintain. All the GLS library functions that compare strings use this function internally to optimize themselves; therefore, you will only find the need to use this macro in highly performance-sensitive code, if ever.
IFX_GL_NULL
This is the value that you must pass as mbs_byte_length if the corresponding multi-byte character string argument is null-terminated. This is also the value that you must pass as wcs_char_length if the corresponding wide-character string argument is null-terminated.
IFX_GL_NO_LIMIT
This is the value that you must pass as mb_byte_limit if the corresponding multi-byte character argument is (1) a character in a null-terminated string, or (2) a character that is not in a null-terminated string and is not otherwise followed by another character, but is known to be in a buffer that contains at least ifx_gl_mb_loc_max() bytes.
IFX_GL_PROC_CS
This macro evaluates to a string that names the current locale's codeset. This macro can be used in conjunction with ifx_gl_conv_needed(), ifx_gl_cv_mconv(), ifx_gl_cv_outbuflen(), ifx_gl_cv_sb2sb_table().

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.