Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

In Dart, Runes are an iterable sequence of 32-bit Unicode code points that represent a string. Because Dart strings are inherently sequences of UTF-16 code units, characters outside the Basic Multilingual Plane (BMP)—such as emojis or complex symbols—are represented in memory by surrogate pairs (two 16-bit units). The Runes class abstracts this UTF-16 encoding complexity, allowing developers to interact directly with the underlying 32-bit Unicode code points.

​
Syntax and String Literals

Within a Dart string literal, Unicode code points are expressed using the \u escape sequence followed by a hexadecimal value.
  • 4-digit hexadecimal: Used for characters within the BMP.
  • Curly braces {}: Required for hexadecimal values containing more or fewer than 4 digits (characters outside the BMP).
String heart = '\u2665';          // 4-digit hex (BMP)
String rocket = '\u{1F680}';      // 5-digit hex (Non-BMP, requires braces)

​
Technical Mechanics: codeUnits vs runes

The distinction between a standard Dart String and Runes becomes apparent when inspecting string length and character data. A string’s .length property returns the number of UTF-16 code units, not the number of visible characters. The .runes property returns an Iterable<int> representing the actual Unicode code points. 
String emoji = '🚀'; 

// UTF-16 Representation
print(emoji.length);          // Output: 2 (Surrogate pair)
print(emoji.codeUnits);       // Output: [55357, 56960]

// 32-bit Unicode Representation
print(emoji.runes.length);    // Output: 1 (Single code point)
print(emoji.runes);           // Output: (128640)

​
Instantiation and Conversion

You can instantiate a Runes object directly from a string, and you can reconstruct a String from an iterable of runes using the String.fromCharCodes() constructor. 
// Extracting runes from a string
Runes runeSequence = Runes('\u2665 \u{1f605}');

// Iterating over the 32-bit integers
for (int codePoint in runeSequence) {
  print(codePoint); 
  // Output: 9829, 32, 128517
}

// Reconstructing a String from Runes
String reconstructed = String.fromCharCodes(runeSequence);
print(reconstructed); // Output: ♥ 😅

​
Character API Alternative

While Runes provide raw integer code points, Dart also offers the characters package (often exposed via the String.characters extension). While Runes handle 32-bit code points, characters handle grapheme clusters (user-perceived characters), which is necessary when a single visual character is composed of multiple Unicode code points (e.g., an emoji with a skin tone modifier).
Master Dart with Deep Grasping Methodology!Learn More