ifx_gl_mbsncat

ifx_gl_mbsncat - concatenate part of one multi-byte string to another

SYNOPSIS

#include <ifxgls.h>
int ifx_gl_mbsncat(gl_mchar_t *mbs1, int mbs1_byte_length, gl_mchar_t *mbs2,
			int mbs2_byte_length, int char_limit)

DESCRIPTION

This function appends mbs2 to the end of mbs1. No more than char_limit characters will be read from mbs2 and written to mbs1. If mbs1 and mbs2 overlap, the results of this function are undefined.

If mbs1_byte_length is the value IFX_GL_NULL then the function will assume that mbs1 is a null-terminated string; otherwise the function assumes that mbs1_byte_length is the number of bytes in mbs1. If mbs2_byte_length is the value IFX_GL_NULL then the function will assume that mbs2 is a null-terminated string; otherwise the function assumes that mbs2_byte_length is the number of bytes in mbs2. See Multi-Byte Character String Termination for more general information about these lengths.

If mbs1_byte_length is equal to IFX_GL_NULL then the function will null-terminate the concatenated string; otherwise it will not.

RETURN VALUES

This function returns the number of bytes in the resulting concatenated string, not including the null terminator, if any.

ERRORS

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

[IFX_GL_PARAMERR]: Either mbs1_byte_length is not equal to IFX_GL_NULL and is not greater than or equal to zero, or mbs2_byte_length is not equal to IFX_GL_NULL and is not greater than or equal to zero.
[IFX_GL_TERMMISMAT]: Either mbs1_byte_length is equal to IFX_GL_NULL and mbs2_byte_length is greater than or equal to zero or mbs1_byte_length is greater than or equal to zero and mbs2_byte_length is equal to IFX_GL_NULL
[IFX_GL_EILSEQ]: Either mbs1 or mbs2 contains an invalid multi-byte character
[IFX_GL_EINVAL]: Either the function cannot determine whether the last character of mbs1 is a valid multi-byte character, because it would need to read more than mbs1_byte_length bytes from mbs1, or the function cannot determine whether the last character of mbs2 is a valid multi-byte character, because it would need to read more than mbs2_byte_length bytes from mbs2. See Keeping Multi-Byte Strings Consistent for more information about this error.

ACKNOWLEDGEMENT