Standard Library

class StringBuilder

A mutable accumulator for building a string from many pieces.

since 0.1.0-alpha.1linuxwindowswasm

Overview

Unlike arrays and strings, a StringBuilder is changed in place: add appends to the same object, so every variable that refers to it sees the new text. Appending many pieces and calling toString once is much cheaper than joining strings with + in a loop. add returns the builder itself, so calls chain, and << is shorthand for add.

Description

StringBuilder collects text piece by piece and produces the final string once. Use it when a loop or a recursive writer appends many fragments, instead of rebuilding a longer string with + at every step.

Unlike Array, Map and Set, which are values, StringBuilder is a class with reference semantics, and mutation across call sites is the point. add(s) appends in place and returns the same builder, so calls chain. A builder passed to a function is the same builder inside it, and every name that refers to it sees every append. The << operator is shorthand for add.

toString() joins all the collected pieces in one pass, and does not change the builder: it can be called repeatedly while you keep adding. length() is the total length of the pieces added so far and isEmpty() is true when nothing, or only empty text, has been added.

Chained adds, shared across a call

StringBuilder sb = StringBuilder();
sb.add("hello").add(", ").add("world");
console.writeln(sb.length());
console.writeln(sb.toString());
sb << "!" << "?";
console.writeln(sb.toString());
void fill(StringBuilder b) { b.add("[x]"); }
fill(sb);
console.writeln(sb.toString());
StringBuilder other = sb;
other.add("+");
console.writeln(sb.toString());
StringBuilder empty = StringBuilder();
console.writeln(empty.isEmpty());

12
hello, world
hello, world!?
hello, world!?[x]
hello, world!?[x]+
true

Rules

• add accepts a string only. To append a number or another value, convert it first, for example sb.add(n.toString()). There is no byte-level append.
• add and << return the builder itself, so sb.add("a").add("b") appends both.
• A builder is shared by reference. Two variables holding the same builder see the same text; make a separate builder when you want a separate result.
• toString() does not clear the builder.

Examples

Building a table row in a loop

StringBuilder sb = StringBuilder();
for (int i in 1..4) {
    if (!sb.isEmpty()) { sb.add(", "); }
    sb.add(i.toString());
}
console.writeln(sb.toString());
console.writeln(sb.length());

1, 2, 3, 4
10

Notes

A builder keeps the added pieces in an array and joins them when toString() is called.

Examples

Building a line

StringBuilder sb = StringBuilder();
sb.add("a").add("b");
sb << "c" << "d";
console.writeln(sb.toString());
console.writeln(sb.length());
StringBuilder alias = sb;
alias.add("!");
console.writeln(sb.toString());

abcd
4
abcd!

Methods

add

add(string s) -> StringBuilder

Append s to the end of the text and return the same builder.

The builder is changed in place. Returning the builder lets calls be chained.

Parameters

s

The text to append.

Returns

The receiver itself, not a copy.

Examples

Chaining

StringBuilder sb = StringBuilder();
StringBuilder same = sb.add("one").add("-").add("two");
console.writeln(sb.toString());
sb.add("!");
console.writeln(same.toString());

one-two
one-two!

isEmpty

isEmpty() -> bool

Whether nothing has been appended yet.

Returns

true when the length is 0.

Examples

Emptiness

StringBuilder sb = StringBuilder();
console.writeln(sb.isEmpty());
sb.add("a");
console.writeln(sb.isEmpty());

true
false

length

length() -> int

The total length of the text appended so far.

Returns

The length of everything added, the same as toString().length().

Examples

Length grows with each add

StringBuilder sb = StringBuilder();
console.writeln(sb.length());
sb.add("hello");
console.writeln(sb.length());

0
5

toString

toString() -> string

The accumulated text as one string.

The builder is not cleared; you can keep appending and call toString again.

Returns

Everything added so far, in order.

Examples

Reading the text

StringBuilder sb = StringBuilder();
sb.add("ab").add("cd");
console.writeln(sb.toString());
sb.add("ef");
console.writeln(sb.toString());

abcd
abcdef

Operators

<<

<<(string s) -> StringBuilder

Append s with the << operator; the same as add.

Parameters

s

The text to append.

Returns

The receiver itself, so << can be chained.

Examples

Appending with <<

StringBuilder sb = StringBuilder();
sb << "x" << "y" << "z";
console.writeln(sb.toString());

xyz

See also: add

See also

• joinToString — Join the elements into one string, with sep between neighbours.
• Array — An ordered sequence of values of one type, Array<T>, with value semantics.