diff --git a/docs/documentation/binding/converters.md b/docs/documentation/binding/converters.md index e405533d..406de86c 100644 --- a/docs/documentation/binding/converters.md +++ b/docs/documentation/binding/converters.md @@ -16,7 +16,7 @@ Four terms carry the page. - An **affinity** is an `int` that a converter reports for its type pair. When several converters serve the same pair, the highest affinity wins. Every built-in converter reports 2, except `EqualityTypeConverter`, which reports 1. - The **converter service** is the table of converters that bindings look in. `BindingConverters.Current` holds it. -The examples set the current culture to the invariant culture, so their output is the same on every machine. In your own app the converters use the current culture, except `SingleToStringTypeConverter` with no hint, which uses the invariant culture. The output below shows the invariant form. +The examples set the current culture to the invariant culture, so their output is the same on every machine. In your own app, numeric converters format and parse with `CultureInfo.CurrentCulture`. This applies to nullable numbers and to conversions with an `int` or `string` hint. Generated bindings use the same culture as the runtime converters. ## Convert one value @@ -107,6 +107,42 @@ A numeric converter to text also takes a hint. An `int` hint sets the minimum di Seven numeric types have a converter in each direction. The parse converters use the `TryParse` method of their type under the current culture. A value outside the range of the target type fails. +Formatting follows the current culture too. This example selects `fr-FR`, where the decimal separator is a comma. A `float`, its nullable counterpart, and both kinds of format hint use that separator. It restores the previous culture after the example. + +```csharp +CultureInfo? previousCulture = CultureInfo.CurrentCulture; +try +{ + CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo("fr-FR"); + const float value = 3.14F; + SingleToStringTypeConverter converter = new SingleToStringTypeConverter(); + NullableSingleToStringTypeConverter nullableConverter = new NullableSingleToStringTypeConverter(); + + _ = converter.TryConvert(value, conversionHint: null, out var plain); + _ = converter.TryConvert(value, conversionHint: 2, out var precision); + _ = converter.TryConvert(value, conversionHint: "F3", out var formatted); + _ = nullableConverter.TryConvert(value, conversionHint: null, out var nullable); + + Console.WriteLine(plain); + Console.WriteLine(precision); + Console.WriteLine(formatted); + Console.WriteLine(nullable); +} +finally +{ + CultureInfo.CurrentCulture = previousCulture; +} +``` + +```text +3,14 +3,14 +3,140 +3,14 +``` + +The hint controls the numeric format, not the culture. For invariant output, supply a conversion lambda or a [custom converter](custom-converters.md) that calls `ToString` with `CultureInfo.InvariantCulture`. + | Type | Text to number | Number to text | | --- | --- | --- | | `byte` | `StringToByteTypeConverter` | `ByteToStringTypeConverter` | @@ -705,7 +741,7 @@ Each row is one built-in converter or one member of this page's topic. Every con | [`ShortToStringTypeConverter`](https://github.com/reactiveui/ReactiveUI.Binding.SourceGenerators/blob/main/src/ReactiveUI.Binding.Shared/Bindings/Converter/ShortToStringTypeConverter.cs) | Formats a `short` as text. | `short` to `string`. | Always succeeds. Hint: an `int` is the minimum digit count, and a `string` is a format string. A malformed format throws `FormatException`. | | [`IntegerToStringTypeConverter`](https://github.com/reactiveui/ReactiveUI.Binding.SourceGenerators/blob/main/src/ReactiveUI.Binding.Shared/Bindings/Converter/IntegerToStringTypeConverter.cs) | Formats an `int` as text. | `int` to `string`. | Always succeeds. Hint: an `int` is the minimum digit count, and a `string` is a format string. A malformed format throws `FormatException`. | | [`LongToStringTypeConverter`](https://github.com/reactiveui/ReactiveUI.Binding.SourceGenerators/blob/main/src/ReactiveUI.Binding.Shared/Bindings/Converter/LongToStringTypeConverter.cs) | Formats a `long` as text. | `long` to `string`. | Always succeeds. Hint: an `int` is the minimum digit count, and a `string` is a format string. A malformed format throws `FormatException`. | -| [`SingleToStringTypeConverter`](https://github.com/reactiveui/ReactiveUI.Binding.SourceGenerators/blob/main/src/ReactiveUI.Binding.Shared/Bindings/Converter/SingleToStringTypeConverter.cs) | Formats a `float` as text. | `float` to `string`. | Always succeeds. With no hint it uses the invariant culture, as a generated binding does, so `7.25` stays `7.25` in fr-FR. Hint: an `int` is the number of decimal places, and a `string` is a format string; both use the current culture. A malformed format throws `FormatException`. | +| [`SingleToStringTypeConverter`](https://github.com/reactiveui/ReactiveUI.Binding.SourceGenerators/blob/main/src/ReactiveUI.Binding.Shared/Bindings/Converter/SingleToStringTypeConverter.cs) | Formats a `float` as text. | `float` to `string`. | Always succeeds. Uses the current culture with or without a hint. Hint: an `int` is the number of decimal places, and a `string` is a format string. A malformed format throws `FormatException`. | | [`DoubleToStringTypeConverter`](https://github.com/reactiveui/ReactiveUI.Binding.SourceGenerators/blob/main/src/ReactiveUI.Binding.Shared/Bindings/Converter/DoubleToStringTypeConverter.cs) | Formats a `double` as text. | `double` to `string`. | Always succeeds. Hint: an `int` is the number of decimal places, and a `string` is a format string. A malformed format throws `FormatException`. | | [`DecimalToStringTypeConverter`](https://github.com/reactiveui/ReactiveUI.Binding.SourceGenerators/blob/main/src/ReactiveUI.Binding.Shared/Bindings/Converter/DecimalToStringTypeConverter.cs) | Formats a `decimal` as text. | `decimal` to `string`. | Always succeeds. Hint: an `int` is the number of decimal places, and a `string` is a format string. A malformed format throws `FormatException`. | | [`StringToDateTimeTypeConverter`](https://github.com/reactiveui/ReactiveUI.Binding.SourceGenerators/blob/main/src/ReactiveUI.Binding.Shared/Bindings/Converter/StringToDateTimeTypeConverter.cs) | Parses text into a `DateTime`. | `string` to `DateTime`. | `null` and unparseable text return `false`. Uses the current culture. |