Meziantou.Framework

UnicodeNormalization Class

Namespace
Meziantou.Framework
Assembly
Meziantou.Framework.Unicode.dll
Package
Meziantou.Framework.Unicode 2.0.15
Source
UnicodeNormalization.cs
Available in package assets
net10.0net11.0

Provides the Unicode normalization forms.

public static class UnicodeNormalization

Remarks

The forms are those of Unicode Standard Annex #15 for UnicodeProperties.UnicodeVersion. They do not use the globalization library of the platform: the results are the same on every platform and every framework version, including in globalization-invariant mode, where String.Normalize only handles ASCII.

An unpaired surrogate is not a character: it is copied as is and never combines. The methods never throw for the content of the text.

See also

Properties

NameDescription
MaxCanonicalDecompositionLengthGets the greatest number of code points of the full canonical decomposition of one code point.

MaxCanonicalDecompositionLength

UnicodeNormalization.cs

Gets the greatest number of code points of the full canonical decomposition of one code point.

public static int MaxCanonicalDecompositionLength { get; }

Property value

int

Methods

NameDescription
GetCanonicalDecomposition(int, Span<int>)Gets the full canonical decomposition of a code point.
GetNormalizedLength(ReadOnlySpan<char>, NormalizationForm)Gets the length of a text once normalized.
IsNormalized(ReadOnlySpan<char>, NormalizationForm)Determines whether a text is in a normalization form.
Normalize(string, NormalizationForm)Returns a text in a normalization form.
TryComposeCanonical(int, int, int)Gets the primary composite of two code points.
TryDecomposeCanonical(int, int, int)Gets the canonical decomposition mapping of a code point: one step of decomposition.
TryNormalize(ReadOnlySpan<char>, Span<char>, int, NormalizationForm)Writes a text in a normalization form to a buffer.

GetCanonicalDecomposition(int, Span<int>)

UnicodeNormalization.cs

Gets the full canonical decomposition of a code point.

public static int GetCanonicalDecomposition(int codePoint, Span<int> destination)

Parameters

codePoint int
The code point.
destination Span<int>
The buffer that receives the code points. UnicodeNormalization.MaxCanonicalDecompositionLength elements are always enough.

Returns

int The number of code points written; 1, the code point itself, when it has no decomposition.

Exceptions

ArgumentException
destination is too small.

GetNormalizedLength(ReadOnlySpan<char>, NormalizationForm)

UnicodeNormalization.cs

Gets the length of a text once normalized.

public static int GetNormalizedLength(ReadOnlySpan<char> source, NormalizationForm form = (NormalizationForm)1)

Parameters

source ReadOnlySpan<char>
The text.
form NormalizationForm
The normalization form.

Returns

int The number of UTF-16 code units UnicodeNormalization.TryNormalize writes.

Exceptions

ArgumentOutOfRangeException
form is not a defined value.

IsNormalized(ReadOnlySpan<char>, NormalizationForm)

UnicodeNormalization.cs

Determines whether a text is in a normalization form.

public static bool IsNormalized(ReadOnlySpan<char> value, NormalizationForm form = (NormalizationForm)1)

Parameters

value ReadOnlySpan<char>
The text.
form NormalizationForm
The normalization form.

Returns

bool true when normalizing the text would not change it.

Exceptions

ArgumentOutOfRangeException
form is not a defined value.

Normalize(string, NormalizationForm)

UnicodeNormalization.cs

Returns a text in a normalization form.

public static string Normalize(string value, NormalizationForm form = (NormalizationForm)1)

Parameters

value string
The text.
form NormalizationForm
The normalization form.

Returns

string The normalized text; value itself when it is already normalized.

Exceptions

ArgumentNullException
value is null.
ArgumentOutOfRangeException
form is not a defined value.

TryComposeCanonical(int, int, int)

UnicodeNormalization.cs

Gets the primary composite of two code points.

public static bool TryComposeCanonical(int first, int second, out int composite)

Parameters

first int
The first code point, a starter.
second int
The second code point.
composite int
The composite, when the method returns true; otherwise 0.

Returns

bool true when the two code points compose under the normalization form C. The pairs excluded from composition return false.

TryDecomposeCanonical(int, int, int)

UnicodeNormalization.cs

Gets the canonical decomposition mapping of a code point: one step of decomposition.

public static bool TryDecomposeCanonical(int codePoint, out int first, out int second)

Parameters

codePoint int
The code point.
first int
The first code point of the mapping, when the method returns true; otherwise codePoint.
second int
The second code point of the mapping, or -1 when the mapping is a single code point.

Returns

bool true when the code point has a canonical decomposition.

Remarks

The first code point can have a decomposition of its own; the second one never has. A Hangul syllable is decomposed into its leading syllable and its trailing consonant, or into its two jamos when it has no trailing consonant.

TryNormalize(ReadOnlySpan<char>, Span<char>, int, NormalizationForm)

UnicodeNormalization.cs

Writes a text in a normalization form to a buffer.

public static bool TryNormalize(ReadOnlySpan<char> source, Span<char> destination, out int charsWritten, NormalizationForm form = (NormalizationForm)1)

Parameters

source ReadOnlySpan<char>
The text.
destination Span<char>
The buffer that receives the normalized text. It must not overlap source.
charsWritten int
The number of UTF-16 code units written, when the method returns true; otherwise 0.
form NormalizationForm
The normalization form.

Returns

bool false when destination is too small; nothing meaningful is written in that case.

Exceptions

ArgumentOutOfRangeException
form is not a defined value.