What are Runes in Dart?

Overview

In Dart, Runes are the Unicode code points of a

String

The Problem: UTF-16 Encoding

A Dart

String

dartCopy
void main() {
  final emoji = '👨';  // U+1F468 (Man emoji)

  print(emoji.length);         // 2 (two UTF-16 code units!)
  print(emoji.codeUnits);      // [55357, 56424] (surrogate pair)
  print(emoji.runes.toList()); // [128104] (one Unicode code point: 0x1F468)
}

String.runes Property

The

runes

Iterable<int>

dartCopy
void main() {
  // ASCII characters — no difference
  const ascii = 'Dart';
  print(ascii.length);             // 4
  print(ascii.runes.toList());     // [68, 97, 114, 116]
  print(ascii.codeUnits);          // [68, 97, 114, 116] (same!)

  // Emoji — runes vs codeUnits differ
  const emoji = '🎯🔥';
  print(emoji.length);             // 4 (each emoji = 2 code units)
  print(emoji.codeUnits.length);   // 4
  print(emoji.runes.length);       // 2 (two actual characters)
  print(emoji.runes.toList());     // [127919, 128293]
}

The Runes Class

Runes

dart:core

dartCopy
void main() {
  const text = 'Hello 🌍';

  // Using Runes class directly
  final runes = Runes(text);
  for (final rune in runes) {
    print('U+${rune.toRadixString(16).toUpperCase()} -> ${String.fromCharCode(rune)}');
  }
  // U+48 -> H
  // U+65 -> e
  // U+6C -> l
  // U+6C -> l
  // U+6F -> o
  // U+20 ->
  // U+1F30D -> 🌍
}

Creating Strings from Runes

Use

String.fromCharCodes()

dartCopy
void main() {
  // Create string from Unicode code points
  final heart = String.fromCharCode(0x2764);    // ❤
  final dart = String.fromCharCodes([0x44, 0x61, 0x72, 0x74]); // Dart
  final emoji = String.fromCharCode(0x1F600);   // 😀

  print(heart);  // ❤
  print(dart);   // Dart
  print(emoji);  // 😀

  // Using rune literals in strings
  print('I \u2764 Dart');         // I ❤ Dart
  print('\u{1F600}');              // 😀 (use {} for > 4 hex digits)
}

Practical Use Cases

1. Correctly Counting Characters

dartCopy
int characterCount(String text) {
  // ❌ Wrong — counts UTF-16 code units
  // return text.length;

  // ✅ Correct — counts actual Unicode characters
  return text.runes.length;
}

void main() {
  print(characterCount('Hello'));    // 5
  print(characterCount('Hello 🌍')); // 7 (not 8!)
}

2. Safe String Manipulation

dartCopy
// ❌ Wrong — may split a surrogate pair
String wrongTruncate(String s, int maxLength) {
  return s.substring(0, maxLength);
}

// ✅ Correct — respects Unicode characters
String safeTruncate(String s, int maxChars) {
  final runes = s.runes.toList();
  if (runes.length <= maxChars) return s;
  return String.fromCharCodes(runes.sublist(0, maxChars));
}

void main() {
  const text = '👨‍👩‍👧‍👦 Family';
  print(safeTruncate(text, 3)); // Safely truncates
}

3. Character Validation

dartCopy
bool containsEmoji(String text) {
  return text.runes.any((rune) => rune > 0xFFFF);
}

void main() {
  print(containsEmoji('Hello'));      // false
  print(containsEmoji('Hello 🎉'));   // true
}

Runes vs codeUnits vs characters

.length

.codeUnits

.runes

.characters

dartCopy
import 'package:characters/characters.dart';

void main() {
  const family = '👨‍👩‍👧‍👦'; // Family emoji (one visual character)

  print(family.length);               // 11 (many code units)
  print(family.codeUnits.length);     // 11
  print(family.runes.length);         // 7  (multiple code points joined by ZWJ)
  print(family.characters.length);    // 1  (one grapheme cluster ✅)
}

Key Insight: Use

textCopy

.runes

when you need true Unicode code points (not UTF-16 code units). For user-visible character counting (especially with complex emojis), use the

textCopy

characters

package for grapheme cluster support.