StringBuilder في C#: Append وInsert وReplace ومتى تستخدمه

النصوص في C# غير قابلة للتغيير: لا تمدّ s += "x" النص s، بل تنشئ نصًا جديدًا يحتوي على المحارف القديمة والجديدة، ويصبح النص القديم نفايات. مرة واحدة لا تعني شيئًا. أما في حلقة تعمل آلاف المرات فكل تكرار ينسخ كل ما بُني حتى الآن، فينمو العمل الكلي مع مربّع الطول.

StringBuilder، في System.Text، مخزن قابل للتغيير. تكتب Append في المساحة الفارغة في النهاية، فيكبر المخزن من حين لآخر، وتصنع ToString() نصًا واحدًا في النهاية.

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);
    }
}

المخرجات:

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

لماذا الضمّ في حلقة بطيء

هذا النص نفسه مبنيًا بالطريقتين. تختلف الأزمنة من جهاز لآخر، فالأرقام أدناه مجرد مثال؛ المهم هو الفجوة، وهي تتسع كلما كبرت الحلقة:

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}");
    }
}

مخرجات على سبيل المثال:

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

مع 20,000 إضافة ينسخ إصدار += قرابة ملياري محرف إجمالًا. أما StringBuilder فينسخ كل محرف نحو مرتين، مرة حين يُضاف ومرة أخرى في ToString()، ولهذا يبقى قرب ميلي ثانية واحدة.

Append وAppendLine وAppendFormat

لـ Append أشكال لكل نوع مدمج، وتعيد المُنشئ نفسه، فيمكن تسلسل الاستدعاءات. تضيف AppendLine سطرًا جديدًا بعد وسيطها. وتأخذ AppendFormat نص تنسيق مركّبًا مثل 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
    }
}

المخرجات:

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

إضافة نص مستوفى (sb.Append($"...")) مقبولة وسهلة القراءة. وفي .NET 6 وما بعده يكتب المترجم القطع مباشرة في المُنشئ دون إنشاء النص الوسيط.

تستخدم AppendLine القيمة Environment.NewLine: \n في Linux وmacOS، و\r\n في Windows. حين تتطلب صيغة ملف نهاية سطر معينة فأضفها بنفسك.

Insert وRemove وReplace والمفهرس

بخلاف النص يمكن تعديل StringBuilder في مكانه:

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}");
    }
}

المخرجات:

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

ضبط Length على قيمة أصغر يقتطع؛ وهي أرخص طريقة لإزالة فاصل زائد في النهاية. تضبط Clear() الطول على 0 وتحتفظ بالمخزن المحجوز، فيمكن إعادة استخدام مُنشئ واحد عبر تكرارات حلقة خارجية.

المفهرس سريع للإضافات الحديثة لكنه قد يكون بطيئًا للوصول العشوائي في مُنشئ كبير جدًا، لأن المحتوى يُخزَّن في قطع مترابطة. إن احتجت إلى قراءة المحارف فاستدعِ ToString() مرة واحدة وفهرس النص.

مشكلة الفاصل الزائد في النهاية

استخدام تقليدي هو بناء قائمة مفصولة بفواصل. إضافة فاصل بعد كل عنصر تترك فاصلًا زائدًا في النهاية:

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));
    }
}

المخرجات:

csharp, dotnet, linq
csharp, dotnet, linq

حين تكون العناصر في مجموعة أصلًا تكون string.Join أقصر وبالسرعة نفسها على الأقل. احتفظ بـ StringBuilder للنص الذي يعتمد شكله على المنطق: أقسام شرطية، وحلقات متداخلة، وتنسيق مختلط.

السعة

يبدأ StringBuilder بمساحة لـ 16 محرفًا. حين تنفد يربط كتلة تخزين جديدة بحجم كل ما يحمله أصلًا، حتى 8,000 محرف لكل كتلة، فتتضاعف سعته ما دام صغيرًا ثم تنمو بخطوات من 8,000 محرف. النمو لا ينسخ النص المخزّن أبدًا. إن كنت تعرف تقريبًا طول النتيجة فمرّر السعة إلى المُنشئ ولن يحتاج المُنشئ إلى النمو أبدًا:

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);
    }
}

المخرجات:

12000
10000
True
True

التحجيم المسبق تحسين لا شرط. النمو يحجز كتلة جديدة لكنه لا ينقل النص الموجود أبدًا، فالافتراضي مناسب ما لم تكن تبني نصوصًا كبيرة كثيرة في مسار ساخن.

متى لا تستخدم StringBuilder

StringBuilder ليس بديلًا أسرع لكل +. يحوّل المترجم أصلًا a + b + c + d في تعبير واحد إلى استدعاء string.Concat واحد، يحسب الطول النهائي وينسخ كل قطعة مرة واحدة، وهو العمل نفسه الذي سيؤديه المُنشئ بشيفرة أكثر. استخدم النصوص العادية حين:

• يكون عدد القطع صغيرًا وثابتًا: $"{first} {last} ({age})".
• تكون القطع في مجموعة وتحتاج إلى فاصل: string.Join(", ", items).
• لا تحتاج القطع إلى فاصل: string.Concat(parts).
• تضمّ بضع مرات خارج أي حلقة.

استخدم StringBuilder حين تضيف داخل حلقة، أو تضيف عددًا من المرات لا تعرفه مسبقًا، أو تعدّل النص (إدراج أو استبدال أو حذف) أثناء بنائه. التحويل ذهابًا وإيابًا (sb.ToString() داخل الحلقة) يضيّع الفائدة؛ استدعها مرة واحدة في النهاية.

التدفقات هي البديل الآخر: لإنتاج ملف كبير اكتب الأسطر إلى StreamWriter أولًا بأول بدل بناء المحتوى كله في الذاكرة. راجع الملفات.