== Why is this an issue?

Composite format strings in C# are evaluated at runtime, which means they are not verified by the compiler. Introducing an ill-formed format item, or indexing mismatch can lead to unexpected behaviors or runtime errors. The purpose of this rule is to perform static validation on composite format strings used in various string formatting functions to ensure their correct usage.
This rule validates the proper behavior of composite formats when invoking the following methods:

* `String.Format`
* `StringBuilder.AppendFormat`
* `Console.Write`
* `Console.WriteLine`
* `TextWriter.Write`
* `TextWriter.WriteLine`
* `Debug.WriteLine(String, Object[])`
* `Trace.TraceError(String, Object[])`
* `Trace.TraceInformation(String, Object[])`
* `Trace.TraceWarning(String, Object[])`
* `TraceSource.TraceInformation(String, Object[])` 

=== Noncompliant code example

[source,csharp,diff-id=1,diff-type=noncompliant]
----
s = string.Format("[0}", arg0); // Noncompliant: square bracket '[' instead of curly bracket '{'
s = string.Format("{{0}", arg0); // Noncompliant: double starting curly brackets '{{'
s = string.Format("{0}}", arg0); // Noncompliant: double ending curly brackets '}}'
s = string.Format("{-1}", arg0); // Noncompliant: invalid index for the format item, must be >= 0
s = string.Format("{0} {1}", arg0); // Noncompliant: two format items in the string but only one argument provided
----

=== Compliant solution

[source,csharp,diff-id=1,diff-type=compliant]
----
s = string.Format("{0}", 42); // Compliant
s = string.Format("{0,10}", 42); // Compliant
s = string.Format("{0,-10}", 42); // Compliant
s = string.Format("{0:0000}", 42); // Compliant
s = string.Format("{2}-{0}-{1}", 1, 2, 3); // Compliant
s = string.Format("no format"); // Compliant
----

=== Exceptions

The rule does not perform any checks on the format specifier, if present (defined after the `:`).
Moreover, no issues are raised in the following cases:

* the format string is not a `const`.
+
[source,csharp]
----
var pattern = "{0} {1} {2}";
var res = string.Format(pattern, 1, 2); // Compliant, non-constant string are not recognized
----

* the argument is not an inline creation array.
+
[source,csharp]
----
var array = new int[] {};
var res = string.Format("{0} {1}", array); // Compliant the rule does not check the size of the array
----

== Resources

=== Documentation

* https://learn.microsoft.com/en-us/dotnet/standard/base-types/composite-formatting[Composite formatting]
* https://learn.microsoft.com/en-us/dotnet/api/system.string.format[String.Format]
* https://learn.microsoft.com/en-us/dotnet/api/system.text.stringbuilder.appendformat[StringBuilder.AppendFormat]
* https://learn.microsoft.com/en-us/dotnet/api/system.console.write[Console.Write]
* https://learn.microsoft.com/en-us/dotnet/api/system.console.writeline[Console.WriteLine]
* https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.write[TextWriter.Write]
* https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.writeline[TextWriter.WriteLine]
* https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.debug.writeline[Debug.WriteLine]
* https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.traceerror[Trace.TraceError]
* https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.traceinformation[Trace.TraceInformation]
* https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace.tracewarning[Trace.TraceWarning]
* https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.tracesource.traceinformation[TraceSource.TraceInformation]
* https://learn.microsoft.com/en-us/dotnet/standard/base-types/formatting-types[Standard format strings]

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

* Invalid string format, the format cannot be null.
* Invalid string format, unbalanced curly brace count.
* Invalid string format, opening curly brace can only be followed by a digit or an opening curly brace.
* Invalid string format, the highest string format item index should not be greater than the arguments count.
* Invalid string format, format items should comply with the following pattern '{index[,alignment][:formatString]}'.
* Invalid string format, all format item indexes should be a number.
* Invalid string format, all format item alignments should be a number.

=== Highlighting

The format string.

'''
== Comments And Links
(visible only on this page)

=== on 31 Aug 2015, 12:39:59 Tamas Vajk wrote:
\[~ann.campbell.2] Could you check the issue message? I can't easily find out the number of placeholders in the format, that's why I can't use the same as in Python.

=== on 31 Aug 2015, 13:03:46 Ann Campbell wrote:
\[~tamas.vajk] the message is fine as far as it goes, but it doesn't cover something like this:

----
var s1 = string.Format("{3}", 1);
----

=== on 18 Jan 2016, 11:05:13 Ann Campbell wrote:
This should eventually cover ``++Console.WriteLine++`` (and some others, I'm told) too.

include::../comments-and-links.adoc[]

endif::env-github,rspecator-view[]
