Function

GLibutf16_to_utf8

Declaration 

gchar*
g_utf16_to_utf8 (
  const gunichar2* str,
  glong len,
  glong* items_read,
  glong* items_written,
  GError** error
)

Description

Convert a string from UTF-16 to UTF-8. The result will be terminated with a 0 byte.

Note that the input is expected to be already in native endianness, an initial byte-order-mark character is not handled specially. g_convert() can be used to convert a byte buffer of UTF-16 data of ambiguous endianness.

Further note that this function does not validate the result string; it may e.g. include embedded NUL characters. The only validation done by this function is to ensure that the input can be correctly interpreted as UTF-16, i.e. it doesn’t contain unpaired surrogates or partial character sequences.

Parameters

str

Type: An array of guint16

A UTF-16 encoded string.

The length of the array is specified in the len argument.
The data is owned by the caller of the function.
len

Type: glong

The maximum length (number of #gunichar2) of str to use. If len < 0, then the string is nul-terminated.

items_read

Type: glong*

Location to store number of words read, or NULL. If NULL, then G_CONVERT_ERROR_PARTIAL_INPUT will be returned in case str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. It’s guaranteed to be non-negative.

The argument will be set by the function.
The argument can be NULL.
items_written

Type: glong*

Location to store number of bytes written, or NULL. The value stored here does not include the trailing 0 byte. It’s guaranteed to be non-negative.

The argument will be set by the function.
The argument can be NULL.
error

Type: GError **

The return location for a recoverable error.

The argument can be NULL.
If the return location is not NULL, then you must initialize it to a NULL GError*.
The argument will left initialized to NULL by the function if there are no errors.
In case of error, the argument will be set to a newly allocated GError; the caller will take ownership of the data, and be responsible for freeing it.

Return value

Type: gchar*

A pointer to a newly allocated UTF-8 string. This value must be freed with g_free(). If an error occurs, NULL will be returned and error set.

The caller of the function takes ownership of the data, and is responsible for freeing it.
The value is a NUL terminated UTF-8 string.