What is the use of the return value of the StringBuilder Append(string...) function?

Question

The complete syntax of StringBuilder's Append(string s) function (and similar functions) is

StringBuilder myStringBuilder.Append(string myString)

since myStringBuilder.Append(string myString) already adds the string to myStringBuilder, I was wondering what the return value is for? I have never seen any example code that makes use of the return value.

According to msdn it does not return a new StringBuilder instance but a reference to the current builder itself (that would be myStringBuilder). I just can't think of a scenario when using the return value makes sense at all, why didn't they make the return type void?

Answer 1

It means you can easily chain calls together:

sb.Append("Foo=").Append(foo).Append("&Bar=").Append(bar);

... instead of using several separate statements:

sb.Append("Foo=");
sb.Append(foo);
sb.Append("&Bar=");
sb.Append(bar);

The fact that it's a single expression means you can also use it in places where you're restricted to a single expression, e.g. field initialization or a return statement. The latter means you can use it for expression-bodied members, too:

public override string ToString() =>
    new StringBuilder("x").Append(...).Append(...).ToString();

(In many cases using string.Format or an interpolated string literal would make more sense, but sometimes StringBuilder is the way forward...)

Answer 2

Just to add more value to Jon Skeet's answer, it would be worth to mention that this is a fluent API design.

It has its pros and cons, but as Jon Skeet has already pointed out, not only with StringBuilder but in many other classes and frameworks, being able to fluently configure or execute things is very interesting.

Maybe the OP has never seen list.Where(x => ...).OrderBy(x => ...).Select(x => ...).ToList(). Or Castle Windsor's fluent configuration API: Component.For<X>().ImplementedBy<Y>().LifeStyleSingleton().

That's why StringBuilder returns the instance from which Append was called: to being able to call other methods as a chain which, sometimes, seems to be easier to understand than many separate sentences.

About the cons

@Jason asked me for the cons in some comment:

Matias, What are the cons?

Taken from my own experience, I believe that there're few cons, but one of most important ones might be that a fluent chain can be harder to debug since you can't go step by step during an interactive debugging session (actually you can step into and step out... but it's less comfortable than going step by step...).

Excepting that con I find fluent design a good way of implementing auto-documented code since sometimes it's just like reading a natural language sentence and keeps things simple (to those that have already got used with fluent design...)