D24 · Every Built-in Method: String, Runes, StringBuffer & RegExp

By the end of this lesson you will know every public member of String, Runes, RuneIterator, StringBuffer, StringSink, Pattern, Match, RegExp and RegExpMatch in the Dart 3.11 SDK (94 members). For each one you will see what it does in plain words, whether it changes anything or returns something new, what it costs and why, what it can throw, and a real example with its real output. You will understand UTF-16 code units, surrogate pairs and runes, and you will be able to explain, with a memory picture, why s += t in a loop is slow and why StringBuffer is fast.

Related lessons: D04 · Strings (the first look at strings, interpolation and escapes) and D22 · Mutable vs Immutable (why strings never change in place, see its section 9). Next lessons in this series cover numbers, iterables, lists, sets, maps and more.

1. What a String is in memory

Some words, defined once:

• Code unit: one 16-bit number (0 to 65535) in the string's storage. Dart strings are UTF-16: the text is stored as a row of code units.
• Object: a package of data on the heap (the big shared storeroom). A String is an object with a header, a length and the code units.
• Immutable: cannot be changed after it is made. Every method on String that seems to "change" it returns a new String (or, when nothing would change, the same one).
• Literal: text you type in the program, like 'hi'. Equal literals are stored once.

Watch what + and += really do. The picture is the Dart VM's: a stack slot holds an arrow to a String object on the heap.

Two strings can have the same letters and still be two different objects. == asks "same letters?", identical asks "same object?".

2. Code units, runes and graphemes

• length, [], codeUnitAt, substring and every index in Dart count code units.
• A lead surrogate is a unit in 0xD800..0xDBFF; a trail surrogate is in 0xDC00..0xDFFF. A lead followed by a trail encodes one code point above 0xFFFF: 0x10000 + ((lead − 0xD800) << 10) + (trail − 0xDC00).
• runes decodes the pairs, so each emoji is ONE number. The characters package (package:characters, shipped with Flutter) goes one level higher and walks graphemes; the core library does not have it.

Type any text (up to 16 UTF-16 units; paste an emoji if you like) and watch the decoder pair up surrogates.

And now the "one character on screen" problem. An accent can be a separate rune, and a family emoji is several people joined by a zero-width joiner (ZWJ, code unit 0x200D):

3. Create, read and inspect

Create: the three String constructors. Read: indexing, length, the two views (codeUnits, runes). Inherited from Object: the members every object has that String uses or overrides. Time costs are for a string of n code units.

Input size → what is feasible: all of these are O(1) except building (fromCharCodes is O(n)) and runes.length (O(n)); n = 10⁷ units is fine.

First, how [] and codeUnitAt read a unit. Type your own text and index (text|index, text 1 to 16 units, index −20 to 20).

Now codeUnits. It does not copy the text: it is a thin read-only wrapper that asks the string for every element.

Building a String from numbers with String.fromCharCodes(codes, start, end). Numbers up to 0xFFFF become one code unit, bigger ones (code points) become a surrogate pair. Type codes|start|end (1 to 8 decimal numbers separated by commas, start and end are positions in that list):

Cards: create

Cards: read and inspect

Cards: inherited from Object

4. Compare and search

compareTo, == and hashCode compare; contains, startsWith, endsWith, indexOf, lastIndexOf, allMatches, matchAsPrefix search. A Pattern argument accepts a String or a RegExp. Input size → what is feasible: the String-pattern search is a plain scan, O(n·m) worst case, so n = 10⁶ text and m ≤ 100 pattern (10⁸ steps) is fine; for a long pattern and a long text use a smarter algorithm (KMP, question q24).

Dictionary order, step by step (type first|second, each 1 to 12 units):

A sliding search. Type text|pattern|start (text 1 to 20 units, pattern 0 to 6, start 0 to 25):

startsWith(pattern, index) and endsWith only look at ONE alignment, so they cost O(m), not O(n·m):

lastIndexOf is the same scan from the right:

allMatches never reports overlapping matches. Type text|pattern (text 1 to 16, pattern 1 to 4 units):

Cards: compare

Cards: search

5. Slice, clean, replace and split

Every member here returns a new String (or a new List of Strings for split), except when nothing changes: then the VM may hand back the same object (trim of a clean string, replaceAll with no match, substring(0)). Input size → what is feasible: all are O(n) in the string size (replaceAll with a String pattern O(n·m)); n = 10⁷ units is fine, but do NOT call them inside a loop over the same long string (that turns O(n) into O(n²)).

split by a String separator. Type text|separator (text 0 to 14 units, separator 0 to 3 units; an empty separator splits between code units):

replaceAll scans left to right and never re-scans replaced text. Type text|from|to (text 1 to 14, from 0 to 4, to 0 to 4 units):

trim only walks while it sees whitespace. Type any text; write invisible characters as \t, \n or   (text 1 to 16 units after decoding):

padLeft and padRight write the padding once per missing position. Type text|width|padding (text 0 to 6 units, width 0 to 12, padding 0 to 3 units):

splitMapJoin walks the text as alternating gaps and matches, converts each piece and joins them:

Cards: slice, clean, replace, split

6. Runes and RuneIterator

Runes is an Iterable<int>, so it also has every Iterable member (length, first, map, toList and so on: lesson D25). Its own members are only the constructor, string, iterator and the fast last. Most of the power sits in RuneIterator, which lets you go forward AND backward.

Walk a text rune by rune, then back. Type any text (1 to 12 UTF-16 units):

The iterator refuses to start inside a surrogate pair:

How a code point above 0xFFFF becomes two code units (String.fromCharCode). Type a code point in hex (0 to 110000):

Cards: Runes and RuneIterator

7. s += t versus StringBuffer

The exact counting. Let each piece be one code unit and let the loop run n times. Iteration i builds a string of length i, which means copying the i − 1 old units and writing 1 new unit: i writes. Total writes = 1 + 2 + ... + n = n(n + 1)/2 = Θ(n²). A StringBuffer keeps the pieces in a list and copies them once in toString(): about n writes (a few more if the VM compacts small parts: still Θ(n)).

First the memory picture of the loop s += 'x'. Type n (1 to 10) and watch a new String object appear every iteration while the old one becomes garbage:

Now count the work for both ways. Type n (1 to 60); the bars show the running total of unit writes:

How does StringBuffer avoid the copying? Here is the real Dart VM implementation (from string_buffer_patch.dart, Dart 3.11) on a small example. Pieces from write are added to a list of parts; single characters from writeCharCode go to a 64-unit scratch array; toString() turns the scratch array into a part and joins all parts in one allocation.

writeAll writes a separator BETWEEN elements, never before the first or after the last. Type items|separator (0 to 6 comma-separated items of 0 to 4 units, separator 0 to 3 units):

A real measurement

The same loop, 3 ways, timed with Stopwatch (best of 5 runs, Dart 3.11.5 on macOS arm64, dart run; verify/d24.dart repeats the experiment on every run and prints its own numbers). Times are the author's measurement, not a promise: your machine will differ but the shape will not.

Multiplying n by 10 multiplied the += time by about 82 (quadratic: ideal 100) and the StringBuffer time by about 9 (linear: ideal 10). Those are exactly the shapes the counting predicts.

Cards: StringBuffer and StringSink

8. Pattern, Match and RegExp

A RegExp uses JavaScript-style regular-expression syntax. Its four flags are multiLine (^/$ at every line), caseSensitive, unicode (work on code points) and dotAll (dot also matches line breaks). Build a RegExp once and reuse it: compiling is the expensive part. A badly written pattern can backtrack exponentially, so never run an untrusted pattern on untrusted text. Input size → what is feasible: a simple pattern scans in O(n): n = 10⁷ is fine.

All matches of a pattern, one by one. Type pattern ~ text (separate with a space, a tilde and a space; text 1 to 24 units; the animation uses the browser's identical regex syntax):

Capture groups and named groups on a date:

The four flags, each with a before and after:

Greedy versus lazy. Type a text (1 to 20 units, no line breaks) that contains < and >:

Cards: Pattern and Match

Cards: RegExp and RegExpMatch

9. Mutable or immutable?

This is the String half of D22 · Mutable vs Immutable. Everything in this lesson sorted by what it can change:

10. Choosing the right tool

Quiz

Interview questions

Cheat sheet: all 94 members

Rules of thumb: a String never changes; indexes count code units; runes counts code points; loops that grow a string use StringBuffer; compile a RegExp once; replaceAll is literal; anchor patterns when you mean "whole string".