# Normalizer2 Class Reference

Unicode normalization functionality for standard Unicode normalization or for using custom mapping tables. More...

`#include <normalizer2.h>`

Inheritance diagram for Normalizer2:

## Public Member Functions
UnicodeString | normalize (const UnicodeString &src, UErrorCode &errorCode) const
| Returns the normalized form of the source string.
virtual UnicodeString & | normalize (const UnicodeString &src, UnicodeString &dest, UErrorCode &errorCode) const =0
| Writes the normalized form of the source string to the destination string (replacing its contents) and returns the destination string.
virtual UnicodeString & | normalizeSecondAndAppend (UnicodeString &first, const UnicodeString &second, UErrorCode &errorCode) const =0
| Appends the normalized form of the second string to the first string (merging them at the boundary) and returns the first string.
virtual UnicodeString & | append (UnicodeString &first, const UnicodeString &second, UErrorCode &errorCode) const =0
| Appends the second string to the first string (merging them at the boundary) and returns the first string.
virtual UBool | isNormalized (const UnicodeString &s, UErrorCode &errorCode) const =0
| Tests if the string is normalized.
virtual UNormalizationCheckResult | quickCheck (const UnicodeString &s, UErrorCode &errorCode) const =0
| Tests if the string is normalized.
virtual int32_t | spanQuickCheckYes (const UnicodeString &s, UErrorCode &errorCode) const =0
| Returns the end of the normalized substring of the input string.
virtual UBool | hasBoundaryBefore (UChar32 c) const =0
| Tests if the character always has a normalization boundary before it, regardless of context.
virtual UBool | hasBoundaryAfter (UChar32 c) const =0
| Tests if the character always has a normalization boundary after it, regardless of context.
virtual UBool | isInert (UChar32 c) const =0
| Tests if the character is normalization-inert.
virtual UClassID | getDynamicClassID () const =0
| ICU "poor man's RTTI", returns a UClassID for the actual class.
## Static Public Member Functions
static const Normalizer2 * | getInstance (const char *packageName, const char *name, UNormalization2Mode mode, UErrorCode &errorCode)
| Returns a Normalizer2 instance which uses the specified data file (packageName/name similar to ucnv_openPackage() and ures_open()/ResourceBundle) and which composes or decomposes text according to the specified mode.
static UClassID | getStaticClassID ()
| ICU "poor man's RTTI", returns a UClassID for this class.

## Detailed Description

Unicode normalization functionality for standard Unicode normalization or for using custom mapping tables.

All instances of this class are unmodifiable/immutable. Instances returned by getInstance() are singletons that must not be deleted by the caller.

The primary functions are to produce a normalized string and to detect whether a string is already normalized. The most commonly used normalization forms are those defined in http://www.unicode.org/unicode/reports/tr15/ However, this API supports additional normalization forms for specialized purposes. For example, NFKC_Casefold is provided via getInstance("nfkc_cf", COMPOSE) and can be used in implementations of UTS #46.

Not only are the standard compose and decompose modes supplied, but additional modes are provided as documented in the Mode enum.

Some of the functions in this class identify normalization boundaries. At a normalization boundary, the portions of the string before it and starting from it do not interact and can be handled independently.

The spanQuickCheckYes() stops at a normalization boundary. When the goal is a normalized string, then the text before the boundary can be copied, and the remainder can be processed with normalizeSecondAndAppend().

The hasBoundaryBefore(), hasBoundaryAfter() and isInert() functions test whether a character is guaranteed to be at a normalization boundary, regardless of context. This is used for moving from one normalization boundary to the next or preceding boundary, and for performing iterative normalization.

Iterative normalization is useful when only a small portion of a longer string needs to be processed. For example, in ICU, iterative normalization is used by the NormalizationTransliterator (to avoid replacing already-normalized text) and ucol_nextSortKeyPart() (to process only the substring for which sort key bytes are computed).

The set of normalization boundaries returned by these functions may not be complete: There may be more boundaries that could be returned. Different functions may return different boundaries.

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Definition at line 77 of file normalizer2.h.

## Member Function Documentation

virtual UnicodeString& Normalizer2::append | ( | UnicodeString & | first,
|  | const UnicodeString & | second,
|  | UErrorCode & | errorCode |
| ) |  |  | const`[pure virtual]`

Appends the second string to the first string (merging them at the boundary) and returns the first string.

The result is normalized if both the strings were normalized. The first and second strings must be different objects.

Parameters:

  | first | string, should be normalized
  | second | string, should be normalized
  | 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:
  first

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implemented in FilteredNormalizer2.

virtual UClassID Normalizer2::getDynamicClassID | ( |  | ) | const`[pure virtual]`

ICU "poor man's RTTI", returns a UClassID for the actual class.

Returns:
  a UClassID for the actual class.

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implements UObject.

Implemented in FilteredNormalizer2.

static const Normalizer2* Normalizer2::getInstance | ( | const char * | packageName,
|  | const char * | name,
|  | UNormalization2Mode | mode,
|  | UErrorCode & | errorCode |
| ) |  |  | `[static]`

Returns a Normalizer2 instance which uses the specified data file (packageName/name similar to ucnv_openPackage() and ures_open()/ResourceBundle) and which composes or decomposes text according to the specified mode.

Returns an unmodifiable singleton instance. Do not delete it.

Use packageName=NULL for data files that are part of ICU's own data. Use name="nfc" and UNORM2_COMPOSE/UNORM2_DECOMPOSE for Unicode standard NFC/NFD. Use name="nfkc" and UNORM2_COMPOSE/UNORM2_DECOMPOSE for Unicode standard NFKC/NFKD. Use name="nfkc_cf" and UNORM2_COMPOSE for Unicode standard NFKC_CF=NFKC_Casefold.

Parameters:

  | packageName | NULL for ICU built-in data, otherwise application data package name
  | name | "nfc" or "nfkc" or "nfkc_cf" or name of custom data file
  | mode | normalization mode (compose or decompose etc.)
  | 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 requested Normalizer2, if successful

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

static UClassID Normalizer2::getStaticClassID | ( |  | ) | `[static]`

ICU "poor man's RTTI", returns a UClassID for this class.

Returns:
  a UClassID for this class.

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Reimplemented in FilteredNormalizer2.

virtual UBool Normalizer2::hasBoundaryAfter | ( | UChar32 | c | ) | const`[pure virtual]`

Tests if the character always has a normalization boundary after it, regardless of context.

If true, then the character does not normalization-interact with following characters. In other words, a string containing this character can be normalized by processing portions up to this character and after this character independently. This is used for iterative normalization. See the class documentation for details. Note that this operation may be significantly slower than hasBoundaryBefore().

Parameters:

  | c | character to test

Returns:
  TRUE if c has a normalization boundary after it

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implemented in FilteredNormalizer2.

virtual UBool Normalizer2::hasBoundaryBefore | ( | UChar32 | c | ) | const`[pure virtual]`

Tests if the character always has a normalization boundary before it, regardless of context.

If true, then the character does not normalization-interact with preceding characters. In other words, a string containing this character can be normalized by processing portions before this character and starting from this character independently. This is used for iterative normalization. See the class documentation for details.

Parameters:

  | c | character to test

Returns:
  TRUE if c has a normalization boundary before it

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implemented in FilteredNormalizer2.

virtual UBool Normalizer2::isInert | ( | UChar32 | c | ) | const`[pure virtual]`

Tests if the character is normalization-inert.

If true, then the character does not change, nor normalization-interact with preceding or following characters. In other words, a string containing this character can be normalized by processing portions before this character and after this character independently. This is used for iterative normalization. See the class documentation for details. Note that this operation may be significantly slower than hasBoundaryBefore().

Parameters:

  | c | character to test

Returns:
  TRUE if c is normalization-inert

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implemented in FilteredNormalizer2.

virtual UBool Normalizer2::isNormalized | ( | const UnicodeString & | s,
|  | UErrorCode & | errorCode |
| ) |  |  | const`[pure virtual]`

Tests if the string is normalized.

Internally, in cases where the quickCheck() method would return "maybe" (which is only possible for the two COMPOSE modes) this method resolves to "yes" or "no" to provide a definitive result, at the cost of doing more work in those cases.

Parameters:

  | s | input string
  | 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:
  TRUE if s is normalized

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implemented in FilteredNormalizer2.

virtual UnicodeString& Normalizer2::normalize | ( | const UnicodeString & | src,
|  | UnicodeString & | dest,
|  | UErrorCode & | errorCode |
| ) |  |  | const`[pure virtual]`

Writes the normalized form of the source string to the destination string (replacing its contents) and returns the destination string.

The source and destination strings must be different objects.

Parameters:

  | src | source string
  | dest | destination string; its contents is replaced with normalized src
  | 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

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implemented in FilteredNormalizer2.

UnicodeString Normalizer2::normalize | ( | const UnicodeString & | src,
|  | UErrorCode & | errorCode |
| ) |  |  | const`[inline]`

Returns the normalized form of the source string.

Parameters:

  | src | source string
  | 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:
  normalized src

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Definition at line 117 of file normalizer2.h.

virtual UnicodeString& Normalizer2::normalizeSecondAndAppend | ( | UnicodeString & | first,
|  | const UnicodeString & | second,
|  | UErrorCode & | errorCode |
| ) |  |  | const`[pure virtual]`

Appends the normalized form of the second string to the first string (merging them at the boundary) and returns the first string.

The result is normalized if the first string was normalized. The first and second strings must be different objects.

Parameters:

  | first | string, should be normalized
  | second | string, will be normalized
  | 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:
  first

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implemented in FilteredNormalizer2.

virtual UNormalizationCheckResult Normalizer2::quickCheck | ( | const UnicodeString & | s,
|  | UErrorCode & | errorCode |
| ) |  |  | const`[pure virtual]`

Tests if the string is normalized.

For the two COMPOSE modes, the result could be "maybe" in cases that would take a little more work to resolve definitively. Use spanQuickCheckYes() and normalizeSecondAndAppend() for a faster combination of quick check + normalization, to avoid re-checking the "yes" prefix.

Parameters:

  | s | input string
  | 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:
  UNormalizationCheckResult

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implemented in FilteredNormalizer2.

virtual int32_t Normalizer2::spanQuickCheckYes | ( | const UnicodeString & | s,
|  | UErrorCode & | errorCode |
| ) |  |  | const`[pure virtual]`

Returns the end of the normalized substring of the input string.

In other words, with `end=spanQuickCheckYes(s, ec);` the substring `UnicodeString(s, 0, end)` will pass the quick check with a "yes" result.

The returned end index is usually one or more characters before the "no" or "maybe" character: The end index is at a normalization boundary. (See the class documentation for more about normalization boundaries.)

When the goal is a normalized string and most input strings are expected to be normalized already, then call this method, and if it returns a prefix shorter than the input string, copy that prefix and use normalizeSecondAndAppend() for the remainder.

Parameters:

  | s | input string
  | 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:
  "yes" span end index

Draft:
  This API may be changed in the future versions and was introduced in ICU 4.4

Implemented in FilteredNormalizer2.

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

- normalizer2.h

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines