ldap_x_wcs_to_utf8s

Syntax

  #include <ldap_utf8.h>
  
  int ldap_x_wcs_to_utf8s (
     char           *utf8str,
     const wchar_t  *wcstr,
     size_t          count);
  

Parameters

utf8str

(OUT) Points to a byte array to receive the converted UTF-8 string. The output string will be null terminated if there is space for it in the buffer.

wcstr

(IN) Address of the null-terminated wide char string to convert.

count

(IN) The size of the output buffer in bytes.

Return Values

If successful, the function returns the number of bytes written to utf8str, excluding the null termination character, if any.

If utf8str is NULL, the function returns the number of bytes required to contain the converted string, excluding the null-termination character. The count parameter is ignored.

If the function encounters a wide character that cannot be mapped to a UTF-8 sequence, the function returns -1.

If the return value equals count, there was not enough space to fit the string and the null terminator in the buffer. As much of the string as will fit is written to the buffer, but it is not null-terminated. A partial character will not be written.

Example

  #define UTFSTRLEN   20
  wchar_t wcstr_in[] = { 0x2620, ’a’, ’b’, ’c’, 0 };
  char utstr_out[UTFSTRLEN];
  int n;
  
  /* Convert a wide char string to a UTF-8 string.
     Returns utstr = { 0xE2, 0x98, 0xA0, ’a’, ’b’, ’c’, 0 }
     Returns n = 6.  ( # bytes written, excl null )
     If n==UTFSTRLEN, the string could not completely fit in the given buffer.
  */
  n = ldap_x_wcs_to_utf8s(utstr_out, wcstr_in, UTFSTRLEN);