Conversions between Unicode and encodings <uniconv.h>
*****************************************************

This include file declares functions for converting between Unicode strings and char * strings in locale encoding or in other specified encodings.

The following function returns the locale encoding.

 -- Function: const char * locale_charset ()
     Determines the current locale's character encoding, and canonicalizes it into one of the canonical names listed in localcharset.h. If the canonical name cannot be determined, the result is a non-canonical name.

     The result must not be freed; it is statically allocated.

     The result of this function can be used as an argument to the iconv_open function in GNU libc, in GNU libiconv, or in the gnulib provided wrapper around the native iconv_open function.  It may not work as an argument to the native iconv_open function directly.

The handling of unconvertible characters during the conversions can be parametrized through the following enumeration type:

 -- Type: enum iconv_ilseq_handler
     This type specifies how unconvertible characters in the input are handled.

 -- Constant: enum iconv_ilseq_handler iconveh_error
     This handler causes the function to return with errno set to EILSEQ.

 -- Constant: enum iconv_ilseq_handler iconveh_question_mark
     This handler produces one question mark ? per unconvertible character.

 -- Constant: enum iconv_ilseq_handler iconveh_question_replacement_character
     This handler produces one U+FFFD per unconvertible character if that fits in the target encoding, otherwise one question mark ? per unconvertible character.

 -- Constant: enum iconv_ilseq_handler iconveh_escape_sequence
     This handler produces an escape sequence \uXXXX or \UXXXXXXXX for each unconvertible character.

The following functions convert between strings in a specified encoding and Unicode strings.

 -- Function: uint8_t * u8_conv_from_encoding (const char *FROMCODE, enum iconv_ilseq_handler HANDLER, const char *SRC, size_t SRCLEN, size_t *OFFSETS, uint8_t *RESULTBUF, size_t *LENGTHP)
 -- Function: uint16_t * u16_conv_from_encoding (const char *FROMCODE, enum iconv_ilseq_handler HANDLER, const char *SRC, size_t SRCLEN, size_t *OFFSETS, uint16_t *RESULTBUF, size_t *LENGTHP)
 -- Function: uint32_t * u32_conv_from_encoding (const char *FROMCODE, enum iconv_ilseq_handler HANDLER, const char *SRC, size_t SRCLEN, size_t *OFFSETS, uint32_t *RESULTBUF, size_t *LENGTHP)
     Converts an entire string, possibly including NUL bytes, from one encoding to UTF-8 encoding.

     Converts a memory region given in encoding FROMCODE.  FROMCODE is as for the iconv_open function.

     The input is in the memory region between SRC (inclusive) and SRC + SRCLEN (exclusive).

     If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this array is filled with offsets into the result, i.e. the character starting at SRC[i] corresponds to the character starting at RESULT[OFFSETS[i]], and other offsets are set to (size_t)(-1).

     RESULTBUF and *LENGTHP should be a scratch buffer and its size, or RESULTBUF can be NULL.

     May erase the contents of the memory at RESULTBUF.

     If successful: The resulting Unicode string (non-NULL) is returned and its length stored in *LENGTHP.  The resulting string is RESULTBUF if no dynamic memory allocation was necessary, or a freshly allocated memory block otherwise.

     In case of error: NULL is returned and errno is set. Particular errno values: EINVAL, EILSEQ, ENOMEM.

 -- Function: char * u8_conv_to_encoding (const char *TOCODE, enum iconv_ilseq_handler HANDLER, const uint8_t *SRC, size_t SRCLEN, size_t *OFFSETS, char *RESULTBUF, size_t *LENGTHP)
 -- Function: char * u16_conv_to_encoding (const char *TOCODE, enum iconv_ilseq_handler HANDLER, const uint16_t *SRC, size_t SRCLEN, size_t *OFFSETS, char *RESULTBUF, size_t *LENGTHP)
 -- Function: char * u32_conv_to_encoding (const char *TOCODE, enum iconv_ilseq_handler HANDLER, const uint32_t *SRC, size_t SRCLEN, size_t *OFFSETS, char *RESULTBUF, size_t *LENGTHP)
     Converts an entire Unicode string, possibly including NUL units, from UTF-8 encoding to a given encoding.

     Converts a memory region to encoding TOCODE.  TOCODE is as for the iconv_open function.

     The input is in the memory region between SRC (inclusive) and SRC + SRCLEN (exclusive).

     If OFFSETS is not NULL, it should point to an array of SRCLEN integers; this array is filled with offsets into the result, i.e. the character starting at SRC[i] corresponds to the character starting at RESULT[OFFSETS[i]], and other offsets are set to (size_t)(-1).

     RESULTBUF and *LENGTHP should be a scratch buffer and its size, or RESULTBUF can be NULL.

     May erase the contents of the memory at RESULTBUF.

     If successful: The resulting Unicode string (non-NULL) is returned and its length stored in *LENGTHP.  The resulting string is RESULTBUF if no dynamic memory allocation was necessary, or a freshly allocated memory block otherwise.

     In case of error: NULL is returned and errno is set. Particular errno values: EINVAL, EILSEQ, ENOMEM.

The following functions convert between NUL terminated strings in a specified encoding and NUL terminated Unicode strings.

 -- Function: uint8_t * u8_strconv_from_encoding (const char *STRING, const char *FROMCODE, enum iconv_ilseq_handler HANDLER)
 -- Function: uint16_t * u16_strconv_from_encoding (const char *STRING, const char *FROMCODE, enum iconv_ilseq_handler HANDLER)
 -- Function: uint32_t * u32_strconv_from_encoding (const char *STRING, const char *FROMCODE, enum iconv_ilseq_handler HANDLER)
     Converts a NUL terminated string from a given encoding.

     The result is malloc allocated, or NULL (with ERRNO set) in case of error.

     Particular errno values: EILSEQ, ENOMEM.

 -- Function: char * u8_strconv_to_encoding (const uint8_t *STRING, const char *TOCODE, enum iconv_ilseq_handler HANDLER)
 -- Function: char * u16_strconv_to_encoding (const uint16_t *STRING, const char *TOCODE, enum iconv_ilseq_handler HANDLER)
 -- Function: char * u32_strconv_to_encoding (const uint32_t *STRING, const char *TOCODE, enum iconv_ilseq_handler HANDLER)
     Converts a NUL terminated string to a given encoding.

     The result is malloc allocated, or NULL (with errno set) in case of error.

     Particular errno values: EILSEQ, ENOMEM.

The following functions are shorthands that convert between NUL terminated strings in locale encoding and NUL terminated Unicode strings.

 -- Function: uint8_t * u8_strconv_from_locale (const char *STRING)
 -- Function: uint16_t * u16_strconv_from_locale (const char *STRING)
 -- Function: uint32_t * u32_strconv_from_locale (const char *STRING)
     Converts a NUL terminated string from the locale encoding.

     The result is malloc allocated, or NULL (with errno set) in case of error.

     Particular errno values: ENOMEM.

 -- Function: char * u8_strconv_to_locale (const uint8_t *STRING)
 -- Function: char * u16_strconv_to_locale (const uint16_t *STRING)
 -- Function: char * u32_strconv_to_locale (const uint32_t *STRING)
     Converts a NUL terminated string to the locale encoding.

     The result is malloc allocated, or NULL (with errno set) in case of error.

     Particular errno values: ENOMEM.