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.
