What is the difference between capacity and maxCapacity in StringBuilder constructor?

Question

There is a constructor in StringBuilder class (int32, int32). You see there are two parameters capacity and maxCapacity respectively.

I have tried to search the difference between capacity and maxCapacity in StringBuilder constructor. But, I didn't get anything to understand that constructor. I have found documentation on msdn. Still, I don't understand why it is required and what is the use of these parameters. Some question still in my mind that where should I use this constructor? And does it help to improve my application's performance?

Answer 1

After reading all answers, Finally, I understand the difference between capacity and maxCapacity. Now I am trying an example to determine the time of process in different scenario. So, I going to share something about StringBuilder Constructor. I have tested StringBuilder.Append method in following cases and i got some results.

The application code is simple

System.Diagnostics.Stopwatch stp = new System.Diagnostics.Stopwatch();
stp.Start();
StringBuilder str = new StringBuilder()
str.Append("12345");  
Console.WriteLine(stp.ElapsedTicks);

In the declaration of StringBuilder i have used following constructors.

ie. StringBuilder str = new StringBuilder(3, 5)

 1. (int32,int32) : (capacity, maxCapacity)
 2. (int32) : (capacity)
 3. () : Without capacity (No Parameters)

The results are as follows

Trial   (capacity,maxCapacity)      (capacity)      Without Capacity
1       31018                       25259           28847
2       32682                       25025           24635
3       32513                       27404           25168
4       31330                       26013           24986
5       31616                       24050           25324

if i create an object of StringBuilder with maxCapacity then it takes more time to append text then other two cases. But, there is no difference between declaring object with capacity and without capacity. I think it takes some time in checking the maximum capacity of defined string builder class object.

Answer 2

From the MSDN : StringBuilder(int,int)

Initializes a new instance of the StringBuilder class that starts with a specified capacity and can grow to a specified maximum.

So the Capcity is the size with which it has tobe started/created and MaxCapacity is the Limitation of the Stringbuilder.

Example 1: Try the following example one by one

StringBuilder str = new StringBuilder(3, 5);
str.Append("1");      //no error as Length 1 <= max limit 5         
str.Append("12");     //no error as Length 2 <= max limit 5           
str.Append("123");    //no error as Length 3 <= max limit 5   
str.Append("1234");   //no error as Length 4 <= max limit 5        
str.Append("12345");  //no error as Length 5 <= max limit 5        
str.Append("123456"); //error as Length 6 is not <= max limit 5  

Example 2: Try the following example all at once

StringBuilder str = new StringBuilder(3, 5);
str.Append("1");      //no error as str Length 1 <= max limit 5         
str.Append("12");     //no error as str Length 3 <= max limit 5           
str.Append("123");    //error as str Length 6 is not <= max limit 5   

EDIT:

Yes MaxCapacity is seldomly used.

StringBuilder(int Capacity) : with Capacity parameter it creates the StringBuilder object in memory.

as soon as user adds items and if the size exceeds its capacity limit then it allocates more memory to accomdate the exceeded characters and it keeps growing untill unless there is no problem with the memory.

StringBuilder(int Capacity,int maxCapacity) : it does the same as above one parameter Constructor but before creating/increasing its runtime memory to accomdate exceeded characters it checks for MAXCAPACITY limit ,if it exceeds the MAXCAPACITY limit then throws the Exception.

---

From the below commnets : As @Sriram said MaxCapacity parameter has nothing to do with memory allocation.

Answer 3

Difference Between

For capacity

If the number of characters to be stored in the current instance exceeds this capacity value, the StringBuilder object allocates additional memory to store them.

However, string builder class provides an efficient way to repeatedly append bits of string to already constructed object.

StringBuilder is Useful if We want to Make a Big String

Capacity represents the contiguous memory allocated to the StringBuilder. Capacity can be >= length of the string. When more data is appended to the StringBuilder than the capacity, StringBuilder automatically increases the capacity. Since the capacity has exceeded (that is contiguous memory is filled up and no more buffer room is available), a larger buffer area is allocated and data is copied from the original memory to this new area.

It does not copy data to new 'instance' but to new 'memory location'. The instance remains the same but points to the new memory location.

Default capacity of StringBuilder if not specified during creation is 16

For maxCapacity

If the number of characters to be stored in the current instance exceeds this maxCapacity value, the StringBuilder object does not allocate additional memory, but instead throws an exception.

The maximum capacity for this implementation is Int32.MaxValue. However, this value is implementation-specific and might be different in other or later implementations

MSDN maxCapacity

Answer 4

• capacity is for the starting capacity of the StringBuilder. Capacity is the current memory that is allocated by the StringBuilder. If you add text, the amount of memory that is allocated needs to be increased if the current capacity is exceeded. This takes some time. In order to avoid resizing the memory of the StringBuilder, you can set it to a higher value and by that increase performance of your application. If you know before how long the strings that you want to build are at maximum with a high probability, this is a good starting point as you reduce the number of memory reallocations.
• maxCapacity marks the maximum capacity of the StringBuilder and allows to limit the amount of memory that is used by the StringBuilder. If you add data to it, the memory won't be increased over this limit, but an exception is thrown. So you can avoid to run into memory problems if somehow your application wants to add to much to the StringBuilder. However, please note that this limit is not respected under some circumstances from .NET 4 (see this link).

So using this constructor allows you to both increase your performance and set a limit. From my experience, I've mostly used the constructor that allows setting the initial capacity and have set a maxCapacity seldom. But you might want to use this constructor if you append data from unknown sources to a StringBuilder, e.g. from a file that is provided by users in order to react early and more gracefully than handling an OutOfMemoryException allows. So using this constructor also increases the robustness of your application.

Answer 5

It's important to understand that objects like a StringBuilder have to provide internal storage for their data. That is generally going to be an array. Usually, the size of that array will be fairly small. As you add data to the object, whenever the data grows beyond the bounds of that array, more space must be allocated. If you specify an initial capacity then the internal array will initially be created with that size. That means that there will be less need to resize the array as data is added. If you know that you will be adding at least N characters to the StringBuilder then it makes sense to specify N as the initial capacity to avoid unnecessary resizing. maxCapacity is the largest size that that internal array can be increased to.