dotnet / dotnet/docs

CompareOptions enum documentation is incorrect for .NET versions which use ICU

Open
#41,052 5 comments 0 reactions 0 assignees View on GitHub
:watch: Not Triaged
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.