ICU 76.1: icu::IDNA Class Reference

ICU 76.1 76.1

Public Member Functions | Static Public Member Functions
icu::IDNA Class Referenceabstract

Abstract base class for IDNA processing. More...

`#include <idna.h>`

Inheritance diagram for icu::IDNA:

## Public Member Functions
| ~IDNA ()
| Destructor.
virtual UnicodeString & | labelToASCII (const UnicodeString &label, UnicodeString &dest, IDNAInfo &info, UErrorCode &errorCode) const =0
| Converts a single domain name label into its ASCII form for DNS lookup.
virtual UnicodeString & | labelToUnicode (const UnicodeString &label, UnicodeString &dest, IDNAInfo &info, UErrorCode &errorCode) const =0
| Converts a single domain name label into its Unicode form for human-readable display.
virtual UnicodeString & | nameToASCII (const UnicodeString &name, UnicodeString &dest, IDNAInfo &info, UErrorCode &errorCode) const =0
| Converts a whole domain name into its ASCII form for DNS lookup.
virtual UnicodeString & | nameToUnicode (const UnicodeString &name, UnicodeString &dest, IDNAInfo &info, UErrorCode &errorCode) const =0
| Converts a whole domain name into its Unicode form for human-readable display.
virtual void | labelToASCII_UTF8 (StringPiece label, ByteSink &dest, IDNAInfo &info, UErrorCode &errorCode) const
| Converts a single domain name label into its ASCII form for DNS lookup.
virtual void | labelToUnicodeUTF8 (StringPiece label, ByteSink &dest, IDNAInfo &info, UErrorCode &errorCode) const
| Converts a single domain name label into its Unicode form for human-readable display.
virtual void | nameToASCII_UTF8 (StringPiece name, ByteSink &dest, IDNAInfo &info, UErrorCode &errorCode) const
| Converts a whole domain name into its ASCII form for DNS lookup.
virtual void | nameToUnicodeUTF8 (StringPiece name, ByteSink &dest, IDNAInfo &info, UErrorCode &errorCode) const
| Converts a whole domain name into its Unicode form for human-readable display.
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor.
virtual UClassID | getDynamicClassID () const
| ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.

## Static Public Member Functions
static IDNA * | createUTS46Instance (uint32_t options, UErrorCode &errorCode)
| Returns an IDNA instance which implements UTS #46.

## Detailed Description

Abstract base class for IDNA processing.

See http://www.unicode.org/reports/tr46/ and http://www.ietf.org/rfc/rfc3490.txt

The IDNA class is not intended for public subclassing.

This C++ API currently only implements UTS #46. The uidna.h C API implements both UTS #46 (functions using UIDNA service object) and IDNA2003 (functions that do not use a service object).

Stable
  ICU 4.6

Definition at line 52 of file idna.h.

## Constructor & Destructor Documentation

## ◆ ~IDNA()

icu::IDNA::~IDNA | ( |  | ) |

Destructor.

Stable
  ICU 4.6

## Member Function Documentation

## ◆ createUTS46Instance()

static IDNA * icu::IDNA::createUTS46Instance | ( | uint32_t | options,
|  | UErrorCode & | errorCode )
| static

Returns an IDNA instance which implements UTS #46.

Returns an unmodifiable instance, owned by the caller. Cache it for multiple operations, and delete it when done. The instance is thread-safe, that is, it can be used concurrently.

UTS #46 defines Unicode IDNA Compatibility Processing, updated to the latest version of Unicode and compatible with both IDNA2003 and IDNA2008.

The worker functions use transitional processing, including deviation mappings, unless UIDNA_NONTRANSITIONAL_TO_ASCII or UIDNA_NONTRANSITIONAL_TO_UNICODE is used in which case the deviation characters are passed through without change. Unicode 15.1 UTS #46 deprecated transitional processing.

Disallowed characters are mapped to U+FFFD.

For available options see the uidna.h header. Operations with the UTS #46 instance do not support the UIDNA_ALLOW_UNASSIGNED option.

By default, the UTS #46 implementation allows all ASCII characters (as valid or mapped). When the UIDNA_USE_STD3_RULES option is used, ASCII characters other than letters, digits, hyphen (LDH) and dot/full stop are disallowed and mapped to U+FFFD.

Parameters

  options | Bit set to modify the processing and error checking. These should include UIDNA_DEFAULT, or UIDNA_NONTRANSITIONAL_TO_ASCII | UIDNA_NONTRANSITIONAL_TO_UNICODE. See option bit set values in uidna.h.
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  the UTS #46 IDNA instance, if successful

Stable
  ICU 4.6

## ◆ labelToASCII()

virtual UnicodeString & icu::IDNA::labelToASCII | ( | const UnicodeString & | label,
|  | UnicodeString & | dest,
|  | IDNAInfo & | info,
|  | UErrorCode & | errorCode ) const
| pure virtual

Converts a single domain name label into its ASCII form for DNS lookup.

If any processing step fails, then info.hasErrors() will be true and the result might not be an ASCII string. The label might be modified according to the types of errors. Labels with severe errors will be left in (or turned into) their Unicode form.

The UErrorCode indicates an error only in exceptional cases, such as a U_MEMORY_ALLOCATION_ERROR.

Parameters

  label | Input domain name label
  dest | Destination string object
  info | Output container of IDNA processing details.
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  dest

Stable
  ICU 4.6

## ◆ labelToASCII_UTF8()

virtual void icu::IDNA::labelToASCII_UTF8 | ( | StringPiece | label,
|  | ByteSink & | dest,
|  | IDNAInfo & | info,
|  | UErrorCode & | errorCode ) const
| virtual

Converts a single domain name label into its ASCII form for DNS lookup.

UTF-8 version of labelToASCII(), same behavior.

Parameters

  label | Input domain name label
  dest | Destination byte sink; Flush()ed if successful
  info | Output container of IDNA processing details.
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  dest

Stable
  ICU 4.6

## ◆ labelToUnicode()

virtual UnicodeString & icu::IDNA::labelToUnicode | ( | const UnicodeString & | label,
|  | UnicodeString & | dest,
|  | IDNAInfo & | info,
|  | UErrorCode & | errorCode ) const
| pure virtual

Converts a single domain name label into its Unicode form for human-readable display.

If any processing step fails, then info.hasErrors() will be true. The label might be modified according to the types of errors.

The UErrorCode indicates an error only in exceptional cases, such as a U_MEMORY_ALLOCATION_ERROR.

Parameters

  label | Input domain name label
  dest | Destination string object
  info | Output container of IDNA processing details.
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  dest

Stable
  ICU 4.6

## ◆ labelToUnicodeUTF8()

virtual void icu::IDNA::labelToUnicodeUTF8 | ( | StringPiece | label,
|  | ByteSink & | dest,
|  | IDNAInfo & | info,
|  | UErrorCode & | errorCode ) const
| virtual

Converts a single domain name label into its Unicode form for human-readable display.

UTF-8 version of labelToUnicode(), same behavior.

Parameters

  label | Input domain name label
  dest | Destination byte sink; Flush()ed if successful
  info | Output container of IDNA processing details.
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  dest

Stable
  ICU 4.6

## ◆ nameToASCII()

virtual UnicodeString & icu::IDNA::nameToASCII | ( | const UnicodeString & | name,
|  | UnicodeString & | dest,
|  | IDNAInfo & | info,
|  | UErrorCode & | errorCode ) const
| pure virtual

Converts a whole domain name into its ASCII form for DNS lookup.

If any processing step fails, then info.hasErrors() will be true and the result might not be an ASCII string. The domain name might be modified according to the types of errors. Labels with severe errors will be left in (or turned into) their Unicode form.

The UErrorCode indicates an error only in exceptional cases, such as a U_MEMORY_ALLOCATION_ERROR.

Parameters

  name | Input domain name
  dest | Destination string object
  info | Output container of IDNA processing details.
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  dest

Stable
  ICU 4.6

## ◆ nameToASCII_UTF8()

virtual void icu::IDNA::nameToASCII_UTF8 | ( | StringPiece | name,
|  | ByteSink & | dest,
|  | IDNAInfo & | info,
|  | UErrorCode & | errorCode ) const
| virtual

Converts a whole domain name into its ASCII form for DNS lookup.

UTF-8 version of nameToASCII(), same behavior.

Parameters

  name | Input domain name
  dest | Destination byte sink; Flush()ed if successful
  info | Output container of IDNA processing details.
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  dest

Stable
  ICU 4.6

## ◆ nameToUnicode()

virtual UnicodeString & icu::IDNA::nameToUnicode | ( | const UnicodeString & | name,
|  | UnicodeString & | dest,
|  | IDNAInfo & | info,
|  | UErrorCode & | errorCode ) const
| pure virtual

Converts a whole domain name into its Unicode form for human-readable display.

If any processing step fails, then info.hasErrors() will be true. The domain name might be modified according to the types of errors.

The UErrorCode indicates an error only in exceptional cases, such as a U_MEMORY_ALLOCATION_ERROR.

Parameters

  name | Input domain name
  dest | Destination string object
  info | Output container of IDNA processing details.
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  dest

Stable
  ICU 4.6

## ◆ nameToUnicodeUTF8()

virtual void icu::IDNA::nameToUnicodeUTF8 | ( | StringPiece | name,
|  | ByteSink & | dest,
|  | IDNAInfo & | info,
|  | UErrorCode & | errorCode ) const
| virtual

Converts a whole domain name into its Unicode form for human-readable display.

UTF-8 version of nameToUnicode(), same behavior.

Parameters

  name | Input domain name
  dest | Destination byte sink; Flush()ed if successful
  info | Output container of IDNA processing details.
  errorCode | Standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  dest

Stable
  ICU 4.6

The documentation for this class was generated from the following file:

- common/unicode/idna.h