Currency Formats

A typical use case for numeric string value formats is a currency. The merge field value comes from a data source and contains a simple Integer and Float value such as the number 24. But the field should render the value with a currency symbol and 2 decimal digits: $24.00.

Text Control's reporting engine MailMerge supports all standard numeric formats, custom numeric formats and standard and custom date and time formats.

Programmatically, the numeric format can be applied to a MailMerge using the NumericFormat property:

TXTextControl.DocumentServer.Fields.MergeField mf =
  new TXTextControl.DocumentServer.Fields.MergeField()
  {
      NumericFormat = "$##,###.00"
  };

Using the UI, the format can be added to the MergeField dialog box:

The above sample shows a custom numeric string format. In order to add a currency symbol and 2 decimal digits, the following format can be used:

$##,###.00

This custom format contains various format specifiers such as zero placeholders, digit placeholders and decimal points.

Consider the following 2 input values in your merge data: 5000 and -5000.

The results for these values and the above string formatter would be:

$5,000.00

-$5,000.00

Another way to get this currency formatting based on the current UI culture is a standard numeric format for currencies with 2 decimal digits:

C2

The results for these values and the above string formatter would be:

$5,000.00

($5,000.00)

Brackets for Negative Values

In case, you don't want to currency symbol, but brackets indicating a negative amount (which is very common in profit and loss statements), you can add two formats in the string formatter separated by a semicolon.

#,##0.00;(#,##0.00)

The results for these values and the above string formatter would be:

5,000.00

(5,000.00)

Examples

The following table lists the standard numeric formats with examples:

Format specifier	Name	Description	Examples
"C" or "c"	Currency	Result: A currency value. Supported by: All numeric types. Precision specifier: Number of decimal digits.	123.456 ("C") -> $123.46
"D" or "d"	Decimal	Result: Integer digits with optional negative sign. Supported by: Integral types only. Precision specifier: Minimum number of digits.	-1234 ("D6") -> -001234
"E" or "e"	Exponential	Result: Exponential notation. Supported by: All numeric types. Precision specifier: Number of decimal digits.	1052.0329112756 ("E") -> 1.052033E+003
"F" or "f"	Fixed-point	Result: Integral and decimal digits with optional negative sign. Supported by: All numeric types. Precision specifier: Number of decimal digits.	1234 ("F1") -> 1234.0
"G" or "g"	General	Result: The most compact of either fixed-point or scientific notation. Supported by: All numeric types. Precision specifier: Number of significant digits.	123.4546 ("G4") -> 123.5
"P" or "p"	Percent	Result: Number multiplied by 100 and displayed with a percent symbol. Supported by: All numeric types. Precision specifier: Desired number of decimal places.	1 ("P") -> 100,00 %
"R" or "r"	Round-trip	Result: A string that can round-trip to an identical number. Supported by: Single, Double, and BigInteger. Precision specifier: Ignored.	-1234567890.12345678 ("R") -> -1234567890.1234567

The next table lists the custom numeric format specifiers and shows samples produced by each format specifier:

Format specifier	Name	Description	Examples
"0"	Zero placeholder	Replaces the zero with the corresponding digit if one is present; otherwise, zero appears in the result string.	1234.5678 ("00000") -> 01235
"#"	Digit placeholder	Replaces the "#" symbol with the corresponding digit if one is present; otherwise, no digit appears in the result string.	0.45678 ("#.##") -> .46
"."	Decimal point	Determines the location of the decimal separator in the result string.	0.45678 ("0.00") -> 0.46
","	Group separator and number scaling	Serves as both a group separator and a number scaling specifier. As a group separator, it inserts a localized group separator character between each group. As a number scaling specifier, it divides a number by 1000 for each comma specified.	2147483647 ("##,#") -> 2,147,483,647
"%"	Percentage placeholder	Multiplies a number by 100 and inserts a localized percentage symbol in the result string.	0.3697 ("%#0.00") -> %36.97
"‰"	Per mille placeholder	Multiplies a number by 1000 and inserts a localized per mille symbol in the result string.	0.03697 ("#0.00‰") -> 36.97‰
\	Escape character	Causes the next character to be interpreted as a literal rather than as a custom format specifier.	987654 ("\###00\#") -> #987654#
'string' or "string"	Literal string delimiter	Indicates that the enclosed characters should be copied to the result string unchanged.	68 ("# ' degrees'") -> 68 degrees
;	Section separator	Defines sections with separate format strings for positive, negative, and zero numbers.	12.345 ("#0.0#;(#0.0#);-\0-") -> 12.35