Standardize quantity formatting on .NET numeric formats (#1721)

## Motivation

UnitsNet v6 has already removed the proprietary `U`, `V`, and `Q`
quantity format strings. This completes that cleanup by removing the
remaining `A` and `S` formats, so quantity format parameters
consistently accept .NET numeric format strings and can be described
accurately with `StringSyntaxAttribute.NumericFormat`.

The historical rationale supports the cleanup:

- `A` only returns unit abbreviations, which are already available
explicitly through generated `GetAbbreviation()` APIs and the
configurable `UnitAbbreviationsCache`.
- #797 intended to remove `S`, and commit 721287d removed its
documentation and tests, but the formatter implementation remained in
v5. This PR completes that cleanup. The discussion in #1450 also noted
that `S` can hide precision and that callers should choose an explicit
numeric format.

## Changes

- Remove `A`/`An` and `S`/`Sn` formatting from `QuantityFormatter` and
`QuantityValue`.
- Throw focused `FormatException` messages for those formerly recognized
formats with migration guidance.
- Keep standard and custom .NET numeric formats, such as `G3`, `F2`,
`N2`, `E2`, and `0.##`.
- Annotate generated quantity formatting, `QuantityFormatter`,
`QuantityValue`, quantity extensions, and type-converter formatting with
`StringSyntaxAttribute.NumericFormat`.
- Add an internal `StringSyntaxAttribute` compatibility definition for
the `netstandard2.0` target.
- Regenerate quantities and tests, and update the string-formatting
guide and v6 upgrade guide.

## Migration

| Removed | Replacement |
|---|---|
| `A`, `A0`, `A1`, ... | `Length.GetAbbreviation(unit)` or
`UnitAbbreviationsCache.GetUnitAbbreviations(unit)` |
| `S`, `S2`, ... | An explicit standard/custom numeric format such as
`G3`, `F2`, `N2`, `E2`, or `0.##` |
| `U` | `quantity.Unit` |
| `V` | `quantity.Value` |
| `Q` | Static metadata such as `Length.Info.Name` |

Currency (`C`) and percent (`P`) formats remain intentionally
unsupported for physical quantities.

Refs #1200.

## Validation

- `generate-code.bat`
- `dotnet build UnitsNet/UnitsNet.csproj --no-restore`
(`netstandard2.0`, `net8.0`, `net9.0`, `net10.0`)
- `dotnet test UnitsNet.Tests --no-restore -f net10.0` (52,506 passed,
16 skipped)
- `dotnet test UnitsNet.Tests --no-restore -f net48` (45,321 passed, 16
skipped)

Author: angularsen

CodeGen/Generators/UnitsNetGen/QuantityGenerator.cs

@@ -1032,7 +1032,9 @@ public override string ToString()
         /// <summary>
         /// Gets the string representation of this instance in the specified format string using the specified format provider, or <see cref=""CultureInfo.CurrentCulture"" /> if null.
         /// </summary>
-        public string ToString(string? format, IFormatProvider? provider)
+        public string ToString(
+            [StringSyntax(StringSyntaxAttribute.NumericFormat)] string? format,
+            IFormatProvider? provider)
         {{
             return QuantityFormatter.Default.Format(this, format, provider);
         }}

CodeGen/Generators/UnitsNetGen/UnitTestBaseClassGenerator.cs

@@ -1255,26 +1255,6 @@ public void ToString_WithSwedishCulture_ReturnsUnitAbbreviationForEnglishCulture
             Writer.WL($@"
         }}
 
-        [Fact]
-        public void ToString_SFormat_FormatsNumberWithGivenDigitsAfterRadixForCurrentCulture()
-        {{
-            var _ = new CultureScope(CultureInfo.InvariantCulture);
-            Assert.Equal(""0.1{_baseUnitEnglishAbbreviation}"", new {_quantity.Name}(0.123456, {_baseUnitFullName}).ToString(""s1""));
-            Assert.Equal(""0.12{_baseUnitEnglishAbbreviation}"", new {_quantity.Name}(0.123456, {_baseUnitFullName}).ToString(""s2""));
-            Assert.Equal(""0.123{_baseUnitEnglishAbbreviation}"", new {_quantity.Name}(0.123456, {_baseUnitFullName}).ToString(""s3""));
-            Assert.Equal(""0.1235{_baseUnitEnglishAbbreviation}"", new {_quantity.Name}(0.123456, {_baseUnitFullName}).ToString(""s4""));
-        }}
-
-        [Fact]
-        public void ToString_SFormatAndCulture_FormatsNumberWithGivenDigitsAfterRadixForGivenCulture()
-        {{
-            var culture = CultureInfo.InvariantCulture;
-            Assert.Equal(""0.1{_baseUnitEnglishAbbreviation}"", new {_quantity.Name}(0.123456, {_baseUnitFullName}).ToString(""s1"", culture));
-            Assert.Equal(""0.12{_baseUnitEnglishAbbreviation}"", new {_quantity.Name}(0.123456, {_baseUnitFullName}).ToString(""s2"", culture));
-            Assert.Equal(""0.123{_baseUnitEnglishAbbreviation}"", new {_quantity.Name}(0.123456, {_baseUnitFullName}).ToString(""s3"", culture));
-            Assert.Equal(""0.1235{_baseUnitEnglishAbbreviation}"", new {_quantity.Name}(0.123456, {_baseUnitFullName}).ToString(""s4"", culture));
-        }}
-
         [Theory]
         [InlineData(null)]
         [InlineData(""en-US"")]

Docs/string-formatting.md

@@ -1,51 +1,65 @@
-# String Formatting
+# String formatting
 
-## Common examples
+Quantity formatting applies a .NET numeric format string to the value and appends the localized
+abbreviation of the quantity's current unit.
 
-Assuming computer running with US English culture.
-```c#
-var length = Length.FromCentimeters(3.14159265358979);
+```csharp
+Length length = Length.FromCentimeters(Math.PI);
 
-// Typical formats
-length.ToString(); // 3.14 cm
-length.ToString("s4"); // 3.1416 cm
+length.ToString();                                      // 3.141592653589793 cm
+length.ToString("F2", CultureInfo.InvariantCulture);   // 3.14 cm
+$"Length: {length:N3}";                                // Length: 3.142 cm with an en-US current culture
+```
+
+The parameterless overload uses the general (`G`) numeric format. Formatting honors the supplied
+`IFormatProvider`, or `CultureInfo.CurrentCulture` when none is supplied.
 
-// Localized
-length.ToString(new CultureInfo("nb-NO")); // 3,14 cm
-length.ToString(new CultureInfo("ru-RU")); // 3,14 sm (Cyrillic)
+```csharp
+length.ToString(CultureInfo.GetCultureInfo("nb-NO")); // 3,141592653589793 cm
+length.ToString(CultureInfo.GetCultureInfo("ru-RU")); // 3,141592653589793 см
+```
 
-// Converted
-length.As(LengthUnit.Meters).ToString(); // 0.13 m
+Convert the quantity before formatting when a different unit is required:
 
-// Use .NET's built-in formatting methods
-Console.WriteLine("Length is {0:v} {0:a}", l); // "Length is 3.14159265358979 ft"
-string.Format("Length is {0:v} {0:a}", l); // "Length is 3.14159265358979 ft"
-$"Length is {l:v} {l:a}"; // "Length is 3.14159265358979 ft"
+```csharp
+Length meters = length.ToUnit(LengthUnit.Meter);
+string text = meters.ToString("G3", CultureInfo.InvariantCulture); // 0.0314 m
 ```
 
-## Standard Quantity Format Strings
+## Numeric formats
 
-| Format specifier | Description | Examples |
-|------------------|-------------|---------|
-| "g" | General quantity pattern. Equivalent to parameterless `ToString()`. Rounds to 2 significant digits after the radix. | `Length.FromFeet(Math.PI).ToString("g")` -> 3.14 ft |
-| `f`, `f2`, ... `e`, `e3`, ... `r` `#.0` `00000.0` | [Standard numeric formatting](https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-numeric-format-strings#standard-format-specifiers) of value, with unit appended. | `Length.FromFeet(Math.PI).ToString("f")` -> 3.140 ft, `Length.FromFeet(Math.PI).ToString("f1")` -> 3.1 ft, `Length.FromFeet(Math.PI).ToString("r")` -> 3.141592653589793 ft, `Length.FromFeet(Math.PI).ToString("e2")` -> 3.14e+000 ft, `Length.FromFeet(Math.PI).ToString("#.0")` -> 3.1 ft, `Length.FromFeet(Math.PI).ToString("00.0")` -> 003.1 ft |
-| "aXX" | Unit abbreviation pattern. If more than one abbreviation is defined for the unit, then XX specifies the zero-indexed position in the array of abbreviations. XX defaults to 0. If the position is not found, `System.FormatException` is thrown. | `Length.FromFeet(Math.PI).ToString("a")` -> ft, `Length.FromFeet(Math.PI).ToString("a0")` -> ft, `Length.FromFeet(Math.PI).ToString("a1")` -> ', `Length.FromFeet(Math.PI).ToString("a2")` -> prime symbol, `Length.FromFeet(Math.PI).ToString("a3")` -> System.FormatException |
-| "q" | Quantity name pattern. Outputs the corresponding QuantityType enum name. | `Length.FromFeet(Math.PI).ToString("q")` -> Length, `Mass.FromTonnes(Math.PI).ToString("u")` -> Mass |
-| "u" | Unit name pattern. Each quantity type has a corresponding unit enum, such as `Length` quantity having `LengthUnit` unit enum with values `Meter`, `Centimeter` etc. This pattern outputs the unit enum name. | `Length.FromFeet(Math.PI).ToString("u")` -> Foot, `Mass.FromTonnes(Math.PI).ToString("u")` -> Tonne |
+UnitsNet accepts standard and custom .NET numeric formats, including:
 
-There are three different overloads of the ToString() method to provide a string representation of a value and its units.
+| Intent | Format | Example |
+|---|---|---|
+| General notation with a precision | `G3` | `3.14 cm` |
+| Fixed decimal places | `F2` | `3.14 cm` |
+| Grouped number with fixed decimals | `N2` | `1,234.50 cm` |
+| Scientific notation | `E2` | `3.14E+000 cm` |
+| Up to two decimal places | `0.##` | `3.14 cm` |
+| Grouped with up to two decimal places | `#,##0.##` | `1,234.5 cm` |
 
-## Number Formatting
+Currency (`C`) and percent (`P`) formats are rejected because adding currency or percent symbols to
+a physical quantity is misleading.
 
-For "g" pattern (or if no pattern is specified), the number will be formatted with scientific notation for very small or very large values to increase readability. We did not find .NET's default behavior to work well for this so we created our own rules.
+See [.NET standard numeric format strings](https://learn.microsoft.com/dotnet/standard/base-types/standard-numeric-format-strings)
+and [.NET custom numeric format strings](https://learn.microsoft.com/dotnet/standard/base-types/custom-numeric-format-strings)
+for the complete syntax.
 
-| Interval | Format | Examples |
-|-----------|-----------|-------------|
-| `(-inf <= x < 1e-03]` | scientific notation | 1e-04; 2.13e-05 |
-| `[1e-03 <= x < 1e+03]` | fixed point notation | 0.001; 0.01; 100 |
-| `[1e+03 <= x < 1e+06]` | fixed point notation with digit grouping | 1,000; 10,000; 100,000 |
-| `[1e+06 <= x <= +inf)` | scientific notation | 1.1e+06; 3.14e+07 |
+## Unit abbreviations
 
-The symbols used for digit grouping and radix point are culture-sensitive. The above examples use `CultureInfo.InvariantCulture`.
+Use the generated quantity API to get the primary localized abbreviation explicitly:
 
-For more examples, refer to the unit tests in [UnitsNet/UnitFormatter.cs](https://github.com/angularsen/UnitsNet/blob/master/UnitsNet/UnitFormatter.cs).
+```csharp
+string abbreviation = Length.GetAbbreviation(LengthUnit.Foot);
+string localized = Length.GetAbbreviation(LengthUnit.Meter, CultureInfo.GetCultureInfo("ru-RU"));
+```
+
+Use the configured abbreviation cache when every accepted abbreviation is needed. This includes
+runtime customizations made through `UnitsNetSetup`:
+
+```csharp
+IReadOnlyList<string> abbreviations = UnitsNetSetup.Default.UnitAbbreviations
+    .GetUnitAbbreviations(LengthUnit.Foot, CultureInfo.InvariantCulture);
+// "ft", "'", "′"
+```

Docs/upgrading-from-5.x-to-6.x.md

@@ -19,6 +19,8 @@ as binary floating point lose precision.
 - Allow `NaN` and infinity values in quantities #1289
 - Exact fractional values, arithmetic and generated unit conversions with `QuantityValue` #1544
 - `UnitsNet.Serialization.SystemTextJson`, with configurable quantity, unit and value converters #1544
+- Annotate numeric format-string parameters with `StringSyntaxAttribute.NumericFormat` so supported IDEs can provide
+  syntax assistance
 
 ## Breaking changes
 
@@ -62,6 +64,13 @@ as binary floating point lose precision.
 
 ### Behavioral change
 
+- Complete the removal of proprietary quantity format strings. Quantity formatting now accepts .NET numeric format
+  strings only; see [String formatting](string-formatting.md).
+    - Replace `A`, `A0`, `A1`, ... with a generated `GetAbbreviation()` method or
+      `UnitAbbreviationsCache.GetUnitAbbreviations()`.
+    - Replace `S`, `S2`, ... with an explicit numeric format such as `G3`, `F2`, `N2`, `E2`, or `0.##`.
+    - Replace `U`, `V`, and `Q` with the `Unit` property, the `Value` property, and static quantity metadata such as
+      `Length.Info.Name`, respectively.
 - Exact rational conversions and arithmetic may produce results that differ from the previous `double` implementation in the least significant digits. Precision can be lost when a `QuantityValue` is converted to `double`; perform that conversion only at boundaries where floating-point behavior is required. #1544
 - Calls to `.As()` and `.ToUnit()` through an `IQuantity` or `IQuantity<TUnitType>` reference now use the `QuantityExtensions` methods and `UnitConverter.Default`. They no longer dispatch to type-specific methods defined by a custom quantity. Custom quantities that need these calls to support conversion must register their conversion functions with `UnitConverter.Default`. #1696
 - Calling these extension methods with an incompatible unit type now throws `UnitNotFoundException` instead of `ArgumentException`. Code that catches `ArgumentException` around interface-based conversions may need to be updated. #1696