Determine when to allocate a destination buffer

Whether you can perform case conversion of multibyte characters in place depends on whether the number of bytes written to the destination buffer is the same as the number of bytes read from the source.

You can determine when to allocate a destination buffer as follows:
  • If the ifx_gl_case_conv_outbuflen() function determines that the size of the source string and its case-converted value are exactly equal, you can perform case conversion in place.
  • If the size of the case-converted value of the source string is not the same as the size of the source string itself, you cannot perform case conversion in place.
If you cannot perform case conversion in place, you must allocate a separate destination buffer. To allocate this buffer, you need to have an estimate of the number of bytes that it needs to hold. Use any of the following methods to determine the number of bytes that might be written to the destination buffer:
  • The ifx_gl_case_conv_outbuflen() function calculates either exactly the number of bytes that will be written to the destination buffer or a close over approximation of the number.

    This function applies to both uppercase and lowercase conversions. The second argument to ifx_gl_case_conv_outbuflen() is the number of bytes in the character source.

  • The ifx_gl_mb_loc_max() function calculates the maximum number of bytes that can be written to the destination buffer for any source value in the current locale.

    This value is always greater than or equal to (>=) the value that the ifx_gl_case_conv_outbuflen() function returns.

  • The macro IFX_GL_MB_MAX returns the maximum number of bytes that can be written to the destination buffer for any source value in any locale.

    This value is always greater than or equal to the value that the ifx_gl_mb_loc_max() function returns.

Of the preceding options, the macro IFX_GL_MB_MAX is the fastest and the only method that can initialize static buffers. The function ifx_gl_case_conv_outbuflen() is the slowest but the most precise.

The following code fragment uses the ifx_gl_mblen() function to determine the size of the source character and the ifx_gl_case_conv_outbuflen() function to determine the estimated size of the case-converted value:
/* Obtain the sizes of the source and destination strings */
src_mb_bytes = ifx_gl_mblen(src_mb, ...);
dst_mb_bytes = ifx_gl_case_conv_outbuflen(src_mb_bytes);

if ( dst_mb_bytes == src_mb_bytes )
/* Sizes of source and case-equivalent characters are the
* same. Perform the case conversion in place */
   {
   retval =
       ifx_gl_tomupper(src_mb, src_mb, IFX_GL_NO_LIMIT);
   }
else
/* Sizes of source and destination characters are NOT the
 * same. Allocate a destination buffer and perform case
 * conversion into this buffer */
   {
   dst_mb = (gl_mchar_t *) malloc(dst_mb_bytes);
   retval =
       ifx_gl_tomupper(dst_mb, src_mb, IFX_GL_NO_LIMIT);
   }