Document Using(StringComparison) and Using(CultureInfo) modifiers for string constraints (#1103)

* Initial plan

* Document Using(StringComparison) and Using(CultureInfo) modifiers for string constraints

Co-authored-by: OsirisTerje <[email protected]>

* Fix CultureInfo examples to use more appropriate Turkish culture case comparison

Co-authored-by: OsirisTerje <[email protected]>

* Improve CultureInfo examples to show both case-sensitive and case-insensitive usage

Co-authored-by: OsirisTerje <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: OsirisTerje <[email protected]>

Author: Copilot

docs/articles/nunit/writing-tests/constraints/EndsWithConstraint.md

@@ -19,6 +19,8 @@ EndsWith(string expected)
 
 ```csharp
 ...IgnoreCase
+...Using(StringComparison comparisonType)
+...Using(CultureInfo culture)
 ```
 
 ## Examples of Use
@@ -30,6 +32,28 @@ Assert.That(phrase, Does.EndWith("!"));
 Assert.That(phrase, Does.EndWith("PASSING!").IgnoreCase);
 ```
 
+### Specifying a StringComparison
+
+```csharp
+Assert.That("Hello World!", Does.EndWith("WORLD!").Using(StringComparison.OrdinalIgnoreCase));
+Assert.That("Hello World!", Does.EndWith("World!").Using(StringComparison.Ordinal));
+```
+
+### Specifying a CultureInfo
+
+The `Using(CultureInfo)` modifier allows for culture-specific string comparisons.
+It can be combined with `.IgnoreCase` for case-insensitive culture-aware comparisons:
+
+```csharp
+// Using Turkish culture where 'i' and 'I' have special casing rules
+Assert.That("text TITLE", Does.EndWith("title").IgnoreCase.Using(new CultureInfo("tr-TR")));
+
+// Culture-specific comparison without case-insensitivity
+Assert.That("Main Straße", Does.EndWith("Straße").Using(new CultureInfo("de-DE")));
+```
+
 ## Notes
 
 1. **EndsWith** may appear only in the body of a constraint expression or when the inherited syntax is used.
+2. Only one `Using` modifier may be specified. Attempting to use multiple `Using` modifiers
+   will throw an `InvalidOperationException`.

docs/articles/nunit/writing-tests/constraints/StartsWithConstraint.md

@@ -19,6 +19,8 @@ StartsWith(string expected)
 
 ```csharp
 ...IgnoreCase
+...Using(StringComparison comparisonType)
+...Using(CultureInfo culture)
 ```
 
 ## Examples of Use
@@ -30,7 +32,29 @@ Assert.That(phrase, Does.StartWith("Make"));
 Assert.That(phrase, Does.Not.StartWith("Break"));
 ```
 
+### Specifying a StringComparison
+
+```csharp
+Assert.That("Hello World!", Does.StartWith("HELLO").Using(StringComparison.OrdinalIgnoreCase));
+Assert.That("Hello World!", Does.StartWith("Hello").Using(StringComparison.Ordinal));
+```
+
+### Specifying a CultureInfo
+
+The `Using(CultureInfo)` modifier allows for culture-specific string comparisons.
+It can be combined with `.IgnoreCase` for case-insensitive culture-aware comparisons:
+
+```csharp
+// Using Turkish culture where 'i' and 'I' have special casing rules
+Assert.That("TITLE text", Does.StartWith("title").IgnoreCase.Using(new CultureInfo("tr-TR")));
+
+// Culture-specific comparison without case-insensitivity
+Assert.That("Straße Street", Does.StartWith("Straße").Using(new CultureInfo("de-DE")));
+```
+
 ## Notes
 
 1. **StartsWith** may appear only in the body of a constraint
    expression or when the inherited syntax is used.
+2. Only one `Using` modifier may be specified. Attempting to use multiple `Using` modifiers
+   will throw an `InvalidOperationException`.

docs/articles/nunit/writing-tests/constraints/SubstringConstraint.md

@@ -18,8 +18,35 @@ Does.Contain(string expected)
 
 ```csharp
 ...IgnoreCase
+...Using(StringComparison comparisonType)
+...Using(CultureInfo culture)
 ```
 
 ## Examples of Use
 
 [!code-csharp[StringConstraintExamples](~/snippets/Snippets.NUnit/ConstraintExamples.cs#StringConstraintExamples)]
+
+### Specifying a StringComparison
+
+```csharp
+Assert.That("Hello World!", Does.Contain("WORLD").Using(StringComparison.OrdinalIgnoreCase));
+Assert.That("Hello World!", Does.Contain("World").Using(StringComparison.Ordinal));
+```
+
+### Specifying a CultureInfo
+
+The `Using(CultureInfo)` modifier allows for culture-specific string comparisons.
+It can be combined with `.IgnoreCase` for case-insensitive culture-aware comparisons:
+
+```csharp
+// Using Turkish culture where 'i' and 'I' have special casing rules
+Assert.That("Hello TITLE World", Does.Contain("title").IgnoreCase.Using(new CultureInfo("tr-TR")));
+
+// Culture-specific comparison without case-insensitivity
+Assert.That("Straße Street", Does.Contain("Straße").Using(new CultureInfo("de-DE")));
+```
+
+## Notes
+
+1. Only one `Using` modifier may be specified. Attempting to use multiple `Using` modifiers
+   will throw an `InvalidOperationException`.