NET-934 Modify S1643: Add benchmarks

rules/S1643/csharp/rule.adoc

@@ -1,30 +1,99 @@
 == Why is this an issue?
 
-``++StringBuilder++`` is more efficient than string concatenation, especially when the operator is repeated over and over as in loops.
+Concatenating multiple string literals or strings using the `+` operator creates a new string object for each concatenation. This can lead to a large number of intermediate string objects and can be inefficient. The `StringBuilder` class is more efficient than string concatenation, especially when the operator is repeated over and over as in loops.
 
-=== Noncompliant code example
+== How to fix it
 
-[source,csharp]
+Replace string concatenation with `StringBuilder`.
+
+=== Code examples
+
+==== Noncompliant code example
+
+[source,csharp,diff-id=1,diff-type=noncompliant]
 ----
 string str = "";
-for (int i = 0; i < arrayOfStrings.Length ; ++i) 
+for (int i = 0; i < arrayOfStrings.Length ; ++i)
 {
   str = str + arrayOfStrings[i];
 }
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,csharp]
+[source,csharp,diff-id=1,diff-type=compliant]
 ----
 StringBuilder bld = new StringBuilder();
-for (int i = 0; i < arrayOfStrings.Length; ++i) 
+for (int i = 0; i < arrayOfStrings.Length; ++i)
 {
   bld.Append(arrayOfStrings[i]);
 }
 string str = bld.ToString();
 ----
 
+== Resources
+
+=== Documentation
+
+* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/system.text.stringbuilder[StringBuilder Class]
+
+=== Benchmarks
+
+[options="header"]
+|===
+| Method               | Runtime              | Mean         | Standard Deviation     | Allocated
+| StringConcatenation  | .NET 9.0             | 45,723.79 us | 4,589.713 us           | 586280.56 KB
+| StringBuilder        | .NET 9.0             |     77.73 us |     1.221 us           |    243.79 KB
+| StringConcatenation  | .NET Framework 4.6.2 | 33,922.61 us |   302.498 us           | 586450.35 KB
+| StringBuilder        | .NET Framework 4.6.2 |    178.14 us |     9.010 us           |    244.15 KB
+|===
+
+
+==== Glossary
+
+* https://en.wikipedia.org/wiki/Arithmetic_mean[Mean]
+* https://en.wikipedia.org/wiki/Standard_deviation[Standard Deviation]
+
+The results were generated by running the following snippet with https://github.com/dotnet/BenchmarkDotNet[BenchmarkDotNet]:
+
+[source,csharp]
+----
+[Params(10_000)]
+public int Iterations;
+
+[Benchmark]
+public void StringConcatenation()
+{
+    string str = "";
+    for (int i = 0; i < Iterations; i++)
+    {
+        str = str + "append";
+    }
+}
+
+[Benchmark]
+public void StringBuilder()
+{
+    StringBuilder builder = new StringBuilder();
+    for (int i = 0; i < Iterations; i++)
+    {
+        builder.Append("append");
+    }
+    _ = builder.ToString();
+}
+----
+
+Hardware Configuration:
+
+[source]
+----
+BenchmarkDotNet v0.14.0, Windows 10 (10.0.19045.5247/22H2/2022Update)
+12th Gen Intel Core i7-12800H, 1 CPU, 20 logical and 14 physical cores
+  [Host]               : .NET Framework 4.8.1 (4.8.9282.0), X64 RyuJIT VectorSize=256
+  .NET 9.0             : .NET 9.0.0 (9.0.24.52809), X64 RyuJIT AVX2
+  .NET Framework 4.6.2 : .NET Framework 4.8.1 (4.8.9282.0), X64 RyuJIT VectorSize=256
+----
+
 ifdef::env-github,rspecator-view[]
 
 '''