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:

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.