Dokumentacja C# z przykładami: StringBuilder

Q: Czym jest StringBuilder w C#?

System.Text.StringBuilder to mutowalny bufor znaków do budowania stringa w wielu krokach. Append dopisuje na koniec bufora zamiast za każdym razem tworzyć nowy string, a ToString() raz tworzy końcowy string. To standardowe narzędzie do budowania tekstu w pętli.

Q: Jak usunąć ostatni znak ze StringBuilder?

Zmniejsz jego Length: if (sb.Length > 0) sb.Length--; usuwa ostatni znak bez kopiowania. sb.Remove(sb.Length - 1, 1) robi to samo. To typowy sposób na pozbycie się przecinka na końcu, choć string.Join w ogóle nie dodaje końcowego separatora.

Q: Czy StringBuilder jest bezpieczny wątkowo?

Nie. Wywoływanie Append na tym samym StringBuilder z kilku wątków naraz może uszkodzić jego zawartość albo rzucić wyjątek. Daj każdemu wątkowi własny builder i połącz wyniki albo chroń współdzielony builder instrukcją lock.

Q: Co dodaje AppendLine w C#?

Tekst, a po nim Environment.NewLine, czyli \r\n w Windows i \n w Linuksie i macOS. Jeśli wynik musi mieć konkretny znak końca linii, na przykład \n w formacie pliku albo \r\n w nagłówku HTTP, dopisz go jawnie przez Append("\n").

Stringi w C# są niemutowalne: s += "x" nie wydłuża s, tylko tworzy nowy string ze starymi znakami i nowymi, a stary string staje się śmieciem. Raz to nic. W pętli wykonywanej tysiące razy każda iteracja kopiuje wszystko, co zbudowano do tej pory, więc łączna praca rośnie z kwadratem długości.

StringBuilder z przestrzeni System.Text to mutowalny bufor. Append zapisuje w wolnym miejscu na końcu, od czasu do czasu powiększając bufor, a ToString() tworzy jeden string na końcu.

using System;
using System.Text;

class Program
{
    static void Main()
    {
        var sb = new StringBuilder();
        sb.Append("Order #");
        sb.Append(1042);                 // any type: calls ToString()
        sb.Append(", total ");
        sb.Append(59.97m);
        sb.AppendLine();                 // a newline
        sb.AppendLine("Status: shipped");
        sb.Append('*', 10);              // a char repeated

        string result = sb.ToString();
        Console.WriteLine(result);
        Console.WriteLine(sb.Length);
    }
}

Wynik:

Order #1042, total 59.97
Status: shipped
**********
51

Dlaczego konkatenacja w pętli jest wolna

Oto ten sam tekst zbudowany na oba sposoby. Czasy zależą od maszyny, więc poniższe liczby to tylko przykład; liczy się różnica, która rośnie razem z pętlą:

using System;
using System.Diagnostics;
using System.Text;

class Program
{
    static void Main()
    {
        const int n = 20_000;

        var watch = Stopwatch.StartNew();
        string s = "";
        for (int i = 0; i < n; i++)
        {
            s += "item" + i + ";";       // copies the whole string every time
        }
        watch.Stop();
        Console.WriteLine($"string +=     {watch.ElapsedMilliseconds} ms, length {s.Length}");

        watch.Restart();
        var sb = new StringBuilder();
        for (int i = 0; i < n; i++)
        {
            sb.Append("item").Append(i).Append(';');
        }
        string built = sb.ToString();
        watch.Stop();
        Console.WriteLine($"StringBuilder {watch.ElapsedMilliseconds} ms, length {built.Length}");
    }
}

Przykładowy wynik:

string +=     482 ms, length 188890
StringBuilder 1 ms, length 188890

Przy 20 000 dopisań wersja z += kopiuje łącznie prawie 2 miliardy znaków. StringBuilder kopiuje każdy znak mniej więcej dwa razy, raz przy dopisaniu i jeszcze raz w ToString(), dlatego trzyma się w okolicach milisekundy.

Append, AppendLine i AppendFormat

Append ma przeciążenia dla każdego wbudowanego typu i zwraca ten sam builder, więc wywołania można łączyć w łańcuch. AppendLine dodaje znak nowej linii po argumencie. AppendFormat przyjmuje złożony string formatu, tak jak string.Format:

using System;
using System.Text;

class Program
{
    static void Main()
    {
        var items = new[] { "Espresso", "Croissant", "Orange juice" };
        var prices = new[] { 2.40m, 3.10m, 4.50m };

        var receipt = new StringBuilder();
        receipt.AppendLine("RECEIPT").AppendLine("-------");

        decimal total = 0;
        for (int i = 0; i < items.Length; i++)
        {
            receipt.AppendFormat("{0,-14}{1,6:F2}", items[i], prices[i]).AppendLine();
            total += prices[i];
        }
        receipt.Append($"{"TOTAL",-14}{total,6:F2}");

        Console.WriteLine(receipt);   // WriteLine calls ToString() for you
    }
}

Wynik:

RECEIPT
-------
Espresso        2.40
Croissant       3.10
Orange juice    4.50
TOTAL          10.00

Dopisanie interpolowanego stringa (sb.Append($"...")) jest w porządku i dobrze się czyta. W .NET 6 i nowszych kompilator zapisuje nawet fragmenty bezpośrednio do buildera, bez tworzenia pośredniego stringa.

AppendLine używa Environment.NewLine: \n w Linuksie i macOS, \r\n w Windows. Gdy format pliku wymaga konkretnego końca linii, dopisz go sam.

Insert, Remove, Replace i indeksator

W przeciwieństwie do stringa StringBuilder można edytować w miejscu:

using System;
using System.Text;

class Program
{
    static void Main()
    {
        var sb = new StringBuilder("Hello World");

        sb.Insert(5, ",");               // Hello, World
        Console.WriteLine(sb);

        sb.Replace("World", "Maya");     // replaces all occurrences
        Console.WriteLine(sb);

        sb.Remove(0, 7);                 // remove 7 chars at index 0
        Console.WriteLine(sb);

        sb[0] = 'm';                     // indexer is writable
        Console.WriteLine(sb);

        sb.Append("!!!");
        sb.Length -= 2;                  // shorten: drop the last 2 chars
        Console.WriteLine(sb);

        sb.Clear();
        Console.WriteLine($"[{sb}] length {sb.Length}");
    }
}

Wynik:

Hello, World
Hello, Maya
Maya
maya
maya!
[] length 0

Ustawienie mniejszej wartości Length obcina tekst; to najtańszy sposób na usunięcie końcowego separatora. Clear() ustawia długość na 0 i zachowuje przydzielony bufor, więc jeden builder można wykorzystać ponownie w kolejnych iteracjach zewnętrznej pętli.

Indeksator jest szybki dla niedawno dopisanych znaków, ale przy losowym dostępie do bardzo dużego buildera może być wolny, bo zawartość jest przechowywana w połączonych fragmentach. Jeśli musisz czytać znaki, wywołaj raz ToString() i indeksuj string.

Problem końcowego separatora

Klasyczne zastosowanie to budowanie listy rozdzielonej przecinkami. Dopisywanie separatora po każdym elemencie zostawia na końcu jeden za dużo:

using System;
using System.Collections.Generic;
using System.Text;

class Program
{
    static void Main()
    {
        var tags = new List<string> { "csharp", "dotnet", "linq" };

        var sb = new StringBuilder();
        foreach (string tag in tags)
        {
            sb.Append(tag).Append(", ");
        }
        if (sb.Length > 0) sb.Length -= 2;   // drop the final ", "
        Console.WriteLine(sb);

        // Usually simpler: let Join place the separators
        Console.WriteLine(string.Join(", ", tags));
    }
}

Wynik:

csharp, dotnet, linq
csharp, dotnet, linq

Gdy elementy są już w kolekcji, string.Join jest krótszy i co najmniej tak samo szybki. StringBuilder zostaw dla tekstu, którego kształt zależy od logiki: warunkowych sekcji, zagnieżdżonych pętli, mieszanego formatowania.

Pojemność

StringBuilder startuje z miejscem na 16 znaków. Gdy miejsce się kończy, dołącza nowy blok pamięci tak duży jak wszystko, co już przechowuje, maksymalnie 8000 znaków na blok, więc póki jest mały, jego pojemność się podwaja, a potem rośnie o 8000 znaków. Powiększanie nigdy nie kopiuje już zapisanego tekstu. Jeśli wiesz mniej więcej, jak długi będzie wynik, przekaż pojemność do konstruktora, a builder nie będzie musiał rosnąć:

using System;
using System.Text;

class Program
{
    static void Main()
    {
        var rows = 1000;
        var sb = new StringBuilder(rows * 12);   // about 12 chars per row
        Console.WriteLine(sb.Capacity);

        for (int i = 1; i <= rows; i++)
        {
            sb.Append("row ").Append(i.ToString("D4")).Append(";\n");
        }
        Console.WriteLine(sb.Length);
        Console.WriteLine(sb.Length <= sb.Capacity);
        Console.WriteLine(sb.MaxCapacity == int.MaxValue);
    }
}

Wynik:

12000
10000
True
True

Wstępne ustalenie rozmiaru to optymalizacja, a nie wymóg. Powiększanie przydziela nowy blok, ale nigdy nie przenosi istniejącego tekstu, więc wartość domyślna wystarcza, chyba że budujesz wiele dużych stringów w gorącej ścieżce.

Kiedy nie używać StringBuilder

StringBuilder nie jest szybszym zamiennikiem każdego +. Kompilator już teraz zamienia a + b + c + d w jednym wyrażeniu na jedno wywołanie string.Concat, które oblicza końcową długość i kopiuje każdy fragment raz, czyli wykonuje tę samą pracę co builder, tylko mniejszym kodem. Używaj zwykłych stringów, gdy:

Liczba fragmentów jest mała i stała: $"{first} {last} ({age})".
Fragmenty są w kolekcji i potrzebują separatora: string.Join(", ", items).
Fragmenty nie potrzebują separatora: string.Concat(parts).
Łączysz stringi kilka razy poza jakąkolwiek pętlą.

Używaj StringBuilder, gdy dopisujesz w pętli, dopisujesz nieznaną z góry liczbę razy albo edytujesz tekst (wstawiasz, zamieniasz, usuwasz) w trakcie budowania. Konwertowanie tam i z powrotem (sb.ToString() wewnątrz pętli) marnuje całą korzyść; wywołaj je raz, na końcu.

Drugą alternatywą są strumienie: żeby utworzyć duży plik, zapisuj linie do StreamWriter na bieżąco, zamiast budować całą zawartość w pamięci. Zobacz pliki.

Najczęściej zadawane pytania

Czym jest StringBuilder w C#?

System.Text.StringBuilder to mutowalny bufor znaków do budowania stringa w wielu krokach. Append dopisuje na koniec bufora zamiast za każdym razem tworzyć nowy string, a ToString() raz tworzy końcowy string. To standardowe narzędzie do budowania tekstu w pętli.

Kiedy używać StringBuilder zamiast łączenia stringów?

Gdy dopisujesz w pętli albo nieznaną liczbę razy, na przykład budując raport, plik CSV lub HTML z kolekcji. Przy kilku stałych fragmentach (a + b + c albo jeden interpolowany string) zwykła konkatenacja jest równie szybka i czytelniejsza, bo kompilator i tak łączy ją w jedno wywołanie string.Concat.

Jak usunąć ostatni znak ze StringBuilder?

Zmniejsz jego Length: if (sb.Length > 0) sb.Length--; usuwa ostatni znak bez kopiowania. sb.Remove(sb.Length - 1, 1) robi to samo. To typowy sposób na pozbycie się przecinka na końcu, choć string.Join w ogóle nie dodaje końcowego separatora.

Czy StringBuilder jest bezpieczny wątkowo?

Nie. Wywoływanie Append na tym samym StringBuilder z kilku wątków naraz może uszkodzić jego zawartość albo rzucić wyjątek. Daj każdemu wątkowi własny builder i połącz wyniki albo chroń współdzielony builder instrukcją lock.

Co dodaje AppendLine w C#?

Tekst, a po nim Environment.NewLine, czyli \r\n w Windows i \n w Linuksie i macOS. Jeśli wynik musi mieć konkretny znak końca linii, na przykład \n w formacie pliku albo \r\n w nagłówku HTTP, dopisz go jawnie przez Append("\n").

Powiązane zagadnienia