@subheading idn2_lookup_u8
@anchor{idn2_lookup_u8}
@deftypefun {int} {idn2_lookup_u8} (const uint8_t * @var{src}, uint8_t ** @var{lookupname}, int @var{flags})
@var{src}: input zero-terminated UTF-8 string in Unicode NFC normalized form.

@var{lookupname}: newly allocated output variable with name to lookup in DNS.

@var{flags}: optional @code{idn2_flags}  to modify behaviour.

Perform IDNA2008 lookup string conversion on domain name  @code{src} , as
described in section 5 of RFC 5891.  Note that the input string
must be encoded in UTF-8 and be in Unicode NFC form.

Pass @code{IDN2_NFC_INPUT}  in  @code{flags} to convert input to NFC form before
further processing.  @code{IDN2_TRANSITIONAL}  and @code{IDN2_NONTRANSITIONAL} 
do already imply @code{IDN2_NFC_INPUT} .

Pass @code{IDN2_ALABEL_ROUNDTRIP}  in  @code{flags} to
convert any input A-labels to U-labels and perform additional
testing. This is default since version 2.2.
To switch this behavior off, pass IDN2_NO_ALABEL_ROUNDTRIP

Pass @code{IDN2_TRANSITIONAL}  to enable Unicode TR46
transitional processing, and @code{IDN2_NONTRANSITIONAL}  to enable
Unicode TR46 non-transitional processing.

Multiple flags may be specified by binary or:ing them together.

After version 2.0.3: @code{IDN2_USE_STD3_ASCII_RULES}  disabled by default.
Previously we were eliminating non-STD3 characters from domain strings
such as _443._tcp.example.com, or IPs 1.2.3.4/24 provided to libidn2
functions. That was an unexpected regression for applications switching
from libidn and thus it is no longer applied by default.
Use @code{IDN2_USE_STD3_ASCII_RULES}  to enable that behavior again.

After version 0.11:  @code{lookupname} may be NULL to test lookup of  @code{src} without allocating memory.

@strong{Returns:} On successful conversion @code{IDN2_OK}  is returned, if the
output domain or any label would have been too long
@code{IDN2_TOO_BIG_DOMAIN}  or @code{IDN2_TOO_BIG_LABEL}  is returned, or
another error code is returned.

@strong{Since:} 0.1
@end deftypefun

@subheading idn2_lookup_ul
@anchor{idn2_lookup_ul}
@deftypefun {int} {idn2_lookup_ul} (const char * @var{src}, char ** @var{lookupname}, int @var{flags})
@var{src}: input zero-terminated locale encoded string.

@var{lookupname}: newly allocated output variable with name to lookup in DNS.

@var{flags}: optional @code{idn2_flags}  to modify behaviour.

Perform IDNA2008 lookup string conversion on domain name  @code{src} , as
described in section 5 of RFC 5891.  Note that the input is assumed
to be encoded in the locale's default coding system, and will be
transcoded to UTF-8 and NFC normalized by this function.

Pass @code{IDN2_ALABEL_ROUNDTRIP}  in  @code{flags} to
convert any input A-labels to U-labels and perform additional
testing. This is default since version 2.2.
To switch this behavior off, pass IDN2_NO_ALABEL_ROUNDTRIP

Pass @code{IDN2_TRANSITIONAL}  to enable Unicode TR46 transitional processing,
and @code{IDN2_NONTRANSITIONAL}  to enable Unicode TR46 non-transitional
processing.

Multiple flags may be specified by binary or:ing them together, for
example @code{IDN2_ALABEL_ROUNDTRIP}  | @code{IDN2_NONTRANSITIONAL} .

The @code{IDN2_NFC_INPUT}  in  @code{flags} is always enabled in this function.

After version 0.11:  @code{lookupname} may be NULL to test lookup of  @code{src} without allocating memory.

@strong{Returns:} On successful conversion @code{IDN2_OK}  is returned, if
conversion from locale to UTF-8 fails then @code{IDN2_ICONV_FAIL}  is
returned, if the output domain or any label would have been too
long @code{IDN2_TOO_BIG_DOMAIN}  or @code{IDN2_TOO_BIG_LABEL}  is returned, or
another error code is returned.

@strong{Since:} 0.1
@end deftypefun

@subheading idn2_to_ascii_4i
@anchor{idn2_to_ascii_4i}
@deftypefun {int} {idn2_to_ascii_4i} (const uint32_t * @var{input}, size_t @var{inlen}, char * @var{output}, int @var{flags})
@var{input}: zero terminated input Unicode (UCS-4) string.

@var{inlen}: number of elements in  @code{input} .

@var{output}: output zero terminated string that must have room for at least 63 characters plus the terminating zero.

@var{flags}: optional @code{idn2_flags}  to modify behaviour.

THIS FUNCTION HAS BEEN DEPRECATED DUE TO A DESIGN FLAW. USE @code{idn2_to_ascii_4i2()}  INSTEAD !

The ToASCII operation takes a sequence of Unicode code points that make
up one domain label and transforms it into a sequence of code points in
the ASCII range (0..7F). If ToASCII succeeds, the original sequence and
the resulting sequence are equivalent labels.

It is important to note that the ToASCII operation can fail.
ToASCII fails if any step of it fails. If any step of the
ToASCII operation fails on any label in a domain name, that domain
name MUST NOT be used as an internationalized domain name.
The method for dealing with this failure is application-specific.

The inputs to ToASCII are a sequence of code points.

ToASCII never alters a sequence of code points that are all in the ASCII
range to begin with (although it could fail). Applying the ToASCII operation multiple
effect as applying it just once.

The default behavior of this function (when flags are zero) is to apply
the IDNA2008 rules without the TR46 amendments. As the TR46
non-transitional processing is nowadays ubiquitous, when unsure, it is
recommended to call this function with the @code{IDN2_NONTRANSITIONAL} 
and the @code{IDN2_NFC_INPUT}  flags for compatibility with other software.

Return value: Returns @code{IDN2_OK}  on success, or error code.

@strong{Since:} 2.0.0

@strong{Deprecated:} 2.1.1: Use @code{idn2_to_ascii_4i2()} .
@end deftypefun

@subheading idn2_to_ascii_4i2
@anchor{idn2_to_ascii_4i2}
@deftypefun {int} {idn2_to_ascii_4i2} (const uint32_t * @var{input}, size_t @var{inlen}, char ** @var{output}, int @var{flags})
@var{input}: zero terminated input Unicode (UCS-4) string.

@var{inlen}: number of elements in  @code{input} .

@var{output}: pointer to newly allocated zero-terminated output string.

@var{flags}: optional @code{idn2_flags}  to modify behaviour.

The ToASCII operation takes a sequence of Unicode code points that make
up one domain label and transforms it into a sequence of code points in
the ASCII range (0..7F). If ToASCII succeeds, the original sequence and
the resulting sequence are equivalent labels.

It is important to note that the ToASCII operation can fail.
ToASCII fails if any step of it fails. If any step of the
ToASCII operation fails on any label in a domain name, that domain
name MUST NOT be used as an internationalized domain name.
The method for dealing with this failure is application-specific.

The inputs to ToASCII are a sequence of code points.

ToASCII never alters a sequence of code points that are all in the ASCII
range to begin with (although it could fail). Applying the ToASCII operation multiple
effect as applying it just once.

The default behavior of this function (when flags are zero) is to apply
the IDNA2008 rules without the TR46 amendments. As the TR46
non-transitional processing is nowadays ubiquitous, when unsure, it is
recommended to call this function with the @code{IDN2_NONTRANSITIONAL} 
and the @code{IDN2_NFC_INPUT}  flags for compatibility with other software.

Return value: Returns @code{IDN2_OK}  on success, or error code.

@strong{Since:} 2.1.1
@end deftypefun

@subheading idn2_to_ascii_4z
@anchor{idn2_to_ascii_4z}
@deftypefun {int} {idn2_to_ascii_4z} (const uint32_t * @var{input}, char ** @var{output}, int @var{flags})
@var{input}: zero terminated input Unicode (UCS-4) string.

@var{output}: pointer to newly allocated zero-terminated output string.

@var{flags}: optional @code{idn2_flags}  to modify behaviour.

Convert UCS-4 domain name to ASCII string using the IDNA2008
rules.  The domain name may contain several labels, separated by dots.
The output buffer must be deallocated by the caller.

The default behavior of this function (when flags are zero) is to apply
the IDNA2008 rules without the TR46 amendments. As the TR46
non-transitional processing is nowadays ubiquitous, when unsure, it is
recommended to call this function with the @code{IDN2_NONTRANSITIONAL} 
and the @code{IDN2_NFC_INPUT}  flags for compatibility with other software.

Return value: Returns @code{IDN2_OK}  on success, or error code.

@strong{Since:} 2.0.0
@end deftypefun

@subheading idn2_to_ascii_8z
@anchor{idn2_to_ascii_8z}
@deftypefun {int} {idn2_to_ascii_8z} (const char * @var{input}, char ** @var{output}, int @var{flags})
@var{input}: zero terminated input UTF-8 string.

@var{output}: pointer to newly allocated output string.

@var{flags}: optional @code{idn2_flags}  to modify behaviour.

Convert UTF-8 domain name to ASCII string using the IDNA2008
rules.  The domain name may contain several labels, separated by dots.
The output buffer must be deallocated by the caller.

The default behavior of this function (when flags are zero) is to apply
the IDNA2008 rules without the TR46 amendments. As the TR46
non-transitional processing is nowadays ubiquitous, when unsure, it is
recommended to call this function with the @code{IDN2_NONTRANSITIONAL} 
and the @code{IDN2_NFC_INPUT}  flags for compatibility with other software.

Return value: Returns @code{IDN2_OK}  on success, or error code.

@strong{Since:} 2.0.0
@end deftypefun

@subheading idn2_to_ascii_lz
@anchor{idn2_to_ascii_lz}
@deftypefun {int} {idn2_to_ascii_lz} (const char * @var{input}, char ** @var{output}, int @var{flags})
@var{input}: zero terminated input UTF-8 string.

@var{output}: pointer to newly allocated output string.

@var{flags}: optional @code{idn2_flags}  to modify behaviour.

Convert a domain name in locale's encoding to ASCII string using the IDNA2008
rules.  The domain name may contain several labels, separated by dots.
The output buffer must be deallocated by the caller.

The default behavior of this function (when flags are zero) is to apply
the IDNA2008 rules without the TR46 amendments. As the TR46
non-transitional processing is nowadays ubiquitous, when unsure, it is
recommended to call this function with the @code{IDN2_NONTRANSITIONAL} 
and the @code{IDN2_NFC_INPUT}  flags for compatibility with other software.

@strong{Returns:} @code{IDN2_OK}  on success, or error code.
Same as described in @code{idn2_lookup_ul()}  documentation.

@strong{Since:} 2.0.0
@end deftypefun

