CompareOptions enum documentation is incorrect for .NET versions which use ICU
- Dominant language
- No language data
- Stars
- 4.8k
- Forks
- 6.1k
- Avg merge
- 19h 10m
- Merged PRs (30d)
- 268
Description
### Describe the issue or suggestion
This feedback is for the `CompareOptions` documentation [here](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.compareoptions?view=net-8.0). This is the options enumeration which can be passed to `String.Compare` to influence how two strings are compared.
Since adopting ICU as the globalization API in .NET 5, the `StringSort` option has been the default for `CompareOptions`, i.e. both it and `None` result in the exact same output. This is not mentioned on the `CompareOptions` page.
Accordingly, the documentation for `CompareOptions` should be updated for .NET 5 and later to:
1. Note the difference between the two Unicode APIs.
2. Note that `None` is now an alias for `StringSort` (or the other way around!).
3. Update the example code to correct the reported output for the `None` option, which is currently incorrect for these more recent versions of .NET. Alternatively, it may be removed entirely, and just noted to be an alias for `StringSort`.
4. Detail how the user may use NLS to restore the `None` option from early .NET Framework releases. These steps are already detailed [here](https://learn.microsoft.com/en-us/dotnet/core/extensions/globalization-icu), so linking to that article may be sufficient.
The example could do with a rewrite at the same time, as it is very old and has several issues:
1. It is inconsistently formatted, with strangely-spaced code like `Array.Sort( myArr, myComp );` and `foreach ( String myStr in myArr )`. (Not to mention use of `String` instead of the more common `string` alias etc.)
2. The example itself 'buries the lede' with half of the code being spent setting up an unneeded `MyStringComparer`.
3. The code does not follow safe formatting conventions and has multiple instances of single-line blocks not being delimited by braces, e.g.:
```csharp
foreach ( String myStr in myArr )
Console.WriteLine( myStr );
```
4. The opening curly brace is on the same line for functions and class declarations, again not following current style conventions.
5. Only one of the many `CompareOption` enum values is actually covered. Several of the others are quite subtle in their effects and would benefit from worked examples.
6. I don't think this has been edited since early .NET Framework days, so many modern syntactic patterns are missing, which means the code looks quite archaic.
7. Variable names are poorly chosen. `myArr` and `myComp` do not provide contextual information about their intended use.
I think the current C# sample code could be rewritten to look something like the following:
```csharp
using System;
using System.Globalization;
using System.Collections.Generic;
public class CompareOptionsSample
{
public static void Main()
{
var wordList = new List { "cant", "bill's", "coop", "cannot", "billet", "can't", "con", "bills", "co-op" };
Console.WriteLine("Before sorting:");
foreach (string word in wordList)
{
Console.WriteLine(word);
}
Console.WriteLine("\nAfter sorting with CompareOptions.StringSort or CompareOptions.None:");
var comparer = StringComparer.Create(CultureInfo.InvariantCulture, CompareOptions.StringSort);
wordList.Sort(comparer);
foreach (string word in wordList)
{
Console.WriteLine(word);
}
}
}
/*
This code produces the following output:
Before sorting:
cant
bill's
coop
cannot
billet
can't
con
bills
co-op
After sorting with CompareOptions.StringSort or CompareOptions.None:
bill's
billet
bills
can't
cannot
cant
co-op
con
coop
*/
```
Additional context may be found in [this previous issue](https://github.com/dotnet/runtime/issues/102579).
Contributor guide
Assessment
This issue has not been assessed yet.