MergeFields are very powerful elements and provide many different options such as additional text that should be added in front or after the field text and a pre-defined format such as UPPERCASE or Title Case.

But the most powerful feature is the string formatter for numeric numbers and date values.

A typical sample for a numeric format 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.

In this case, the numeric format of the field can be used to render the required format:

MailMerge: Formatting strings in merge fields

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

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

$##,###.00
C2

Results:

2400 -> $2,400.00

The first is a custom format with various format specifiers such as zero placeholdes, digit placeholders and decimal points.

The second is a standard numeric format for currencies with 2 decimal digits. The following table lists the standard numeric formats with examples (from MSDN):

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

In order to keep clean data in database tables, the formatting of numeric strings should be part of the template. The string formatter provides a powerful way to format numeric strings or date values.