A grapheme cluster is one text element, such as a joined emoji or a letter with an accent.
dotnet add package RecursiveAI.OneDiffRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using OneDiff; var diff = Diff.Graphemes( "Hi 👩💻!", "Hi 👩🔬!"); foreach (var run in diff.Pieces) Console.WriteLine( $"{run.Kind}: [{run.Text}]");
Unzip the example, then dotnet run.
Prints the unchanged text and each whole emoji on its own change line.
Equal: [Hi ] Delete: [👩💻] Insert: [👩🔬] Equal: [!]
The full program
The first pair changes 👩💻 to 👩🔬. The second changes the last letter of Cafe from e plus a combining acute accent (\u0301) to e plus a combining grave accent (\u0300).
using OneDiff; Print(Diff.Graphemes("Hi 👩💻!", "Hi 👩🔬!")); Console.WriteLine(); Print(Diff.Graphemes("Cafe\u0301", "Cafe\u0300")); static void Print(TextDiff diff) { foreach (var run in diff.Pieces) Console.WriteLine($"{run.Kind}: [{run.Text}]"); }
dotnet run prints:
Equal: [Hi ] Delete: [👩💻] Insert: [👩🔬] Equal: [!] Equal: [Caf] Delete: [é] Insert: [è]
The brackets delimit each run and make the space after Hi visible. The emoji runs contain the complete old and new sequences; the accent runs include the base e on both sides. If your terminal can’t display the joined emoji, inspect the strings rather than using their appearance as a boundary check.
Variations
Compare by character instead. Replace the second Print(Diff.Graphemes(…)) call with this one to see where the character diff draws the boundary:
Print(Diff.Characters("Cafe\u0301", "Cafe\u0300"));For that pair, the equal run is [Cafe], and the two change runs hold only the acute and grave marks:
Equal: [Cafe] Delete: [́] Insert: [̀]
The deletion is U+0301 (combining acute accent); the insertion is U+0300 (combining grave accent). The marks can be hard to see without a base letter.
Related recipes
The short answer
Call Diff.Graphemes(before, after) when you want changed text to start and end at grapheme boundaries. Read Pieces to get ordered Equal, Delete, and Insert runs. In the example, the woman, joiner, and profession symbol form a single cluster on each side, so the diff deletes one whole emoji and inserts the other instead of leaving the shared prefix behind.
What is a grapheme cluster in C#?
A grapheme cluster is a unit of text that a reader typically treats as one character. .NET calls it a text element. As Microsoft’s text element guide explains, one text element can contain several Unicode code points. OneDiff’s grapheme tokenizer uses .NET’s text-element rules.
A run isn’t necessarily one grapheme. In the example, [Hi ] is one equal run covering three adjacent graphemes. When you read Script.Edits directly, the start and length values count tokens, not positions in the C# string. Use Pieces for the text itself, or OldSpan and NewSpan to get the slice on a particular side of an edit.
What’s the difference between a grapheme and a code point?
A code point is an individual value in Unicode. In a C# string it can take one or two UTF-16 code units. Diff.Characters keeps a valid surrogate pair together, but it does not group a base letter with its combining mark. In the variation, that leaves e in the equal run and makes the marks separate edits. That can be useful when investigating exactly which code point differs. Use graphemes when drawing a change highlight around the whole letter is more useful than highlighting the mark by itself.
Why can two Unicode strings look the same but compare differently?
A precomposed é and e followed by a combining acute accent can look alike without having the same code units. Grapheme segmentation answers where the text element ends; it doesn’t change its contents or make distinct spellings equal. OneDiff compares its tokens exactly by default. That distinction matters when you want the edit report to preserve differences in the original strings, even when they aren’t apparent on screen.