C#のStringBuilder.EnsureCapacity()メソッドとは？使い方とサンプルコードで解説

C#のStringBuilder.EnsureCapacity()メソッドは、StringBuilderインスタンスの容量（Capacity）が指定された値以上であることを保証するためのメソッドです。文字列の連結や追加を繰り返す前に必要な容量をあらかじめ確保しておくことで、内部バッファの再割り当てが発生しにくくなり、パフォーマンス向上が期待できます。

構文

EnsureCapacity()メソッドの構文は次のとおりです。

public int EnsureCapacity (int capacity);

引数 capacity には、保証したい最小容量を指定します。戻り値としては、この呼び出しによって確保された実際の容量が返されます。

• 現在の容量が指定値以上の場合：容量は変更されません。
• 現在の容量が指定値より小さい場合：容量が拡張されます。
• 負の値や最大容量を超える値を指定した場合：例外がスローされます。

使用例1

まずは基本的な使用例を見てみましょう。

using System;
using System.Text;
public class Demo{
    public static void Main(){
        StringBuilder strBuilder = new StringBuilder("jhbjhb");
        Console.WriteLine("String = "+strBuilder);
        Console.WriteLine("StringBuilder capacity= "+strBuilder.Capacity);
        strBuilder.EnsureCapacity(20);
        Console.WriteLine("StringBuilder capacity= "+strBuilder.Capacity);
        char[] arr = new char[5] {'a', 'b', 'c', 'd', 'e'};
        strBuilder.CopyTo(1, arr, 1, 3);
        Console.WriteLine("\nCopied String in char array...");
        Console.WriteLine(arr);
    }
}

実行結果

上記のプログラムを実行すると、次のような出力が得られます。

String = jhbjhb
StringBuilder capacity= 16
StringBuilder capacity= 20
Copied String in char array...
ahbje

初期状態では容量が16ですが、EnsureCapacity(20)を呼び出したことで容量が20以上に拡張されていることがわかります。

使用例2

続いて別の例を見てみましょう。こちらでは容量（Capacity）と長さ（Length）の違いにも注目してください。

using System;
using System.Text;
public class Demo{
    public static void Main(){
        StringBuilder strBuilder = new StringBuilder("Katie");
        Console.WriteLine("String = "+strBuilder);
        Console.WriteLine("\nStringBuilder capacity = "+strBuilder.Capacity);
        Console.WriteLine("StringBuilder length = "+strBuilder.Length);
        strBuilder.EnsureCapacity(35);
        Console.WriteLine("\nStringBuilder capacity= "+strBuilder.Capacity);
        Console.WriteLine("StringBuilder length = "+strBuilder.Length);
        strBuilder.EnsureCapacity(0);
        strBuilder.Length = 0;
        Console.WriteLine("\nStringBuilder capacity= "+strBuilder.Capacity);
        Console.WriteLine("StringBuilder length = "+strBuilder.Length);
    }
}

実行結果

上記のプログラムを実行すると、次のような出力が得られます。

String = Katie
StringBuilder capacity = 16
StringBuilder length = 5
StringBuilder capacity= 35
StringBuilder length = 5
StringBuilder capacity= 35
StringBuilder length = 0

EnsureCapacity(35)によって容量が35に拡張されていますが、Length（実際の文字数）は5のまま変わりません。また、Lengthを0にして内容をクリアしても、確保済みの容量は維持されることが確認できます。

ポイントまとめ

• StringBuilderの既定の初期容量は16です。
• EnsureCapacity()は、現在の容量が指定値未満の場合にのみ容量を拡張します。
• 容量を拡張してもLength（文字列の長さ）には影響しません。
• 大量の文字列操作を行う前に容量を確保しておくと、再割り当てのオーバーヘッドを削減できます。