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 Mail
╰ TX Text Control .NET Server for ASP.NET
╰ DocumentServer Namespace
╰ MailMerge Class
The MailMerge class is a .NET component that can be used to effortlessly merge template documents with database content in .NET projects, such as ASP.NET web applications, web services or Windows services. 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 Mail ╰ TX Text Control .NET Server for ASP.NET
╰ DocumentServer.Fields Namespace
╰ MergeField Class
The MergeField class implements the MS Word specific MERGEFIELD field. using the Numeric ╰ TX Text Control .NET Server for ASP.NET
╰ DocumentServer.Fields Namespace
╰ MergeField Class
╰ NumericFormat Property
Specifies a string format which is applied to numeric values. 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 |
