Documentation of <uniconv.h>.

1 files changed, 134 insertions, 0 deletions

diff --git a/doc/uniconv.texi b/doc/uniconv.texi
new file mode 100644
index 0000000..8ff8ffa
--- /dev/null
+++ b/doc/uniconv.texi
@@ -0,0 +1,134 @@
+@node uniconv.h
+@chapter Conversions between Unicode and encodings @code{<uniconv.h>}
+
+This include file declares functions for converting between Unicode strings
+and @code{char *} strings in locale encoding or in other specified encodings.
+
+The following function returns the locale encoding.
+
+@deftypefun {const char *} locale_charset ()
+Determines the current locale's character encoding, and canonicalizes it
+into one of the canonical names listed in @file{config.charset}.
+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 @code{iconv_open}
+function in GNU libc, in GNU libiconv, or in the gnulib provided wrapper
+around the native @code{iconv_open} function.  It may not work as an argument
+to the native @code{iconv_open} function directly.
+@end deftypefun
+
+The following functions convert between strings in a specified encoding and
+Unicode strings.
+
+@deftypefun int u8_conv_from_encoding (const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler}, const char *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, uint8_t **@var{resultp}, size_t *@var{lengthp})
+@deftypefunx int u16_conv_from_encoding (const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler}, const char *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, uint16_t **@var{resultp}, size_t *@var{lengthp})
+@deftypefunx int u32_conv_from_encoding (const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler}, const char *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, uint32_t **@var{resultp}, size_t *@var{lengthp})
+Converts an entire string, possibly including NUL bytes, from one encoding
+to UTF-8 encoding.
+
+Converts a memory region given in encoding @var{fromcode}.  @var{fromcode} is
+as for the @code{iconv_open} function.
+
+The input is in the memory region between @var{src} (inclusive) and
+@code{@var{src} + @var{srclen}} (exclusive).
+
+If @var{offsets} is not NULL, it should point to an array of @var{srclen}
+integers; this array is filled with offsets into the result, i.e@. the
+character starting at @code{@var{src}[i]} corresponds to the character starting
+at @code{(*@var{resultp})[@var{offsets}[i]]}, and other offsets are set to
+@code{(size_t)(-1)}.
+
+@code{*@var{resultp}} and @code{*@var{lengthp}} should initially be a scratch
+buffer and its size, or @code{*@var{resultp}} can initially be NULL.
+
+May erase the contents of the memory at @code{*@var{resultp}}.
+
+Return value: 0 if successful, otherwise -1 and @code{errno} set.
+If successful: The resulting string is stored in @code{*@var{resultp}} and
+its length in @code{*@var{lengthp}}.  @code{*@var{resultp}} is set to a
+freshly allocated memory block, or is unchanged if no dynamic memory allocation
+was necessary.
+
+Particular @code{errno} values: @code{EINVAL}, @code{EILSEQ}, @code{ENOMEM}.
+@end deftypefun
+
+@deftypefun int u8_conv_to_encoding (const char *@var{tocode}, enum iconv_ilseq_handler @var{handler}, const uint8_t *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, char **@var{resultp}, size_t *@var{lengthp})
+@deftypefunx int u16_conv_to_encoding (const char *@var{tocode}, enum iconv_ilseq_handler @var{handler}, const uint16_t *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, char **@var{resultp}, size_t *@var{lengthp})
+@deftypefunx int u32_conv_to_encoding (const char *@var{tocode}, enum iconv_ilseq_handler @var{handler}, const uint32_t *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, char **@var{resultp}, size_t *@var{lengthp})
+Converts an entire Unicode string, possibly including NUL units, from UTF-8
+encoding to a given encoding.
+
+Converts a memory region to encoding @var{tocode}.  @var{tocode} is as for
+the @code{iconv_open} function.
+
+The input is in the memory region between @var{src} (inclusive) and
+@code{@var{src} + @var{srclen}} (exclusive).
+
+If @var{offsets} is not NULL, it should point to an array of @var{srclen}
+integers; this array is filled with offsets into the result, i.e@. the
+character starting at @code{@var{src}[i]} corresponds to the character starting
+at @code{(*@var{resultp})[@var{offsets}[i]]}, and other offsets are set to
+@code{(size_t)(-1)}.
+
+@code{*@var{resultp}} and @code{*@var{lengthp}} should initially be a scratch
+buffer and its size, or @code{*@var{resultp}} can initially be NULL.
+
+May erase the contents of the memory at @code{*@var{resultp}}.
+
+Return value: 0 if successful, otherwise -1 and @code{errno} set.
+If successful: The resulting string is stored in @code{*@var{resultp}} and
+its length in @code{*@var{lengthp}}.  @code{*@var{resultp}} is set to a
+freshly allocated memory block, or is unchanged if no dynamic memory allocation
+was necessary.
+
+Particular @code{errno} values: @code{EINVAL}, @code{EILSEQ}, @code{ENOMEM}.
+@end deftypefun
+
+The following functions convert between NUL terminated strings in a specified
+encoding and NUL terminated Unicode strings.
+
+@deftypefun {uint8_t *} u8_strconv_from_encoding (const char *@var{string}, const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler})
+@deftypefunx {uint16_t *} u16_strconv_from_encoding (const char *@var{string}, const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler})
+@deftypefunx {uint32_t *} u32_strconv_from_encoding (const char *@var{string}, const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler})
+Converts a NUL terminated string from a given encoding.
+
+The result is @code{malloc} allocated, or NULL (with @var{errno} set) in case of error.
+
+Particular @code{errno} values: @code{EILSEQ}, @code{ENOMEM}.
+@end deftypefun
+
+@deftypefun {char *} u8_strconv_to_encoding (const uint8_t *@var{string}, const char *@var{tocode}, enum iconv_ilseq_handler @var{handler})
+@deftypefunx {char *} u16_strconv_to_encoding (const uint16_t *@var{string}, const char *@var{tocode}, enum iconv_ilseq_handler @var{handler})
+@deftypefunx {char *} u32_strconv_to_encoding (const uint32_t *@var{string}, const char *@var{tocode}, enum iconv_ilseq_handler @var{handler})
+Converts a NUL terminated string to a given encoding.
+
+The result is @code{malloc} allocated, or NULL (with @code{errno} set) in case of error.
+
+Particular @code{errno} values: @code{EILSEQ}, @code{ENOMEM}.
+@end deftypefun
+
+The following functions are shorthands that convert between NUL terminated
+strings in locale encoding and NUL terminated Unicode strings.
+
+@deftypefun {uint8_t *} u8_strconv_from_locale (const char *@var{string})
+@deftypefunx {uint16_t *} u16_strconv_from_locale (const char *@var{string})
+@deftypefunx {uint32_t *} u32_strconv_from_locale (const char *@var{string})
+Converts a NUL terminated string from the locale encoding.
+
+The result is @code{malloc} allocated, or NULL (with @code{errno} set) in case of error.
+
+Particular @code{errno} values: @code{ENOMEM}.
+@end deftypefun
+
+@deftypefun {char *} u8_strconv_to_locale (const uint8_t *@var{string})
+@deftypefunx {char *} u16_strconv_to_locale (const uint16_t *@var{string})
+@deftypefunx {char *} u32_strconv_to_locale (const uint32_t *@var{string})
+Converts a NUL terminated string to the locale encoding.
+
+The result is @code{malloc} allocated, or NULL (with @code{errno} set) in case of error.
+
+Particular @code{errno} values: @code{ENOMEM}.
+@end deftypefun