Method TryFormat

TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider?)

Formats this value's currency and amount into a span of characters.

Declaration

public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider)

Parameters

Type	Name	Description
Span<char>	destination	The span of characters into which this instance will be written.
int	charsWritten	When the method returns, contains the length of the span in number of characters.
ReadOnlySpan<char>	format	The string format to use.
IFormatProvider	provider	The format provider that will be used to obtain number format and culture/region information. If a CultureInfo object is used as the format provider and the format specifies region-specific behavior then this must be a region-specific culture, or if it is not a CultureInfo object then CurrentCulture is used as a fallback and must be region-specific.

Returns

Type	Description
bool	true if the formatting operation succeeds; otherwise false.

Implements

ISpanFormattable.TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider)

Remarks

A destination buffer length of 96 characters is recommended to ensure all possible MonetaryValue values can be formatted.

String format is composed of 3 parts, any of which can be omitted as long as the included specifiers appear in the following order:

1. Currency format specifier:

• "G" General: Use currency code before the amount for English, Irish, Latvian and Maltese language cultures; otherwise currency code after the amount.
• "I" International: Use currency code before the amount ("USD 1.23").
• "R" Reverse International / Round-trip: Use currency code after the amount ("1.23 USD").
• "L" Local: If the currency is local to the culture's region use "C" (currency symbol) formatting, otherwise use "G" (general) formatting. If the culture is not region-specific then general formatting is always used.
• "C"Currency symbol: Use currency symbol with placement dictated by the format provider ($1.23).

The default currency format is "G" (general).

2. Number format specifier:

• "N"Number: Use group separators
• "D"Digits: Do not use group separators

The default number format is "N" (number with group separators).

3. Decimals format specifier:

• "*" Use no decimal places if possible, otherwise currency's decimal places if possible, otherwise as many decimals as needed to represent the value.
• "B" Use the currency's decimal places (or a custom fixed number of decimal places following "B") with banker's "to even" rounding
• "A" Use the currency's decimal places (or a custom fixed number of decimal places following "A") with "away from zero" rounding

The default uses the currency's decimal places if possible, otherwise as many decimals as needed to represent the value. If a fixed number of decimal places is specified after "B" or "A", it must be between 0 and 28.

Exceptions

Type	Condition
FormatException	Format specifier was invalid.
ArgumentException	A region-specific culture is required for the format specified.