Skip to main content

Numeric Format Switch

  • 4 minutes to read

\# [ “ ] switch-argument [ “ ]

A numeric switch-argument is like a numeric format string. If a switch-argument contains spaces, enclose it in quotation marks. You can combine the following items to construct a format string.

Item Usage
# Specifies the numeric places to display in the result. If the result does not include a digit in that place, a space is displayed.
0 (zero) Specifies the numeric places to display in the result. If the result does not include a digit in that place, a 0 (zero) is displayed.
. (decimal point) Determines the decimal point position. The actual decimal symbol in a field code and a field result is dependent on the local Culture. You can use the RichEditMailMergeOptions.CustomSeparators options to specify the custom decimal separator.
, (digit grouping symbol) Separates a series of three digits. The actual symbol in a field code and a field result is dependent on the local Culture. You can use the RichEditMailMergeOptions.CustomSeparators options to specify the custom group separator.
x Drops digits to the left of the “x” placeholder. If the placeholder is to the right of the decimal point, the result is rounded to that position.
- (minus sign) Adds a minus sign to a negative result, or adds a space if the result is positive or 0 (zero).
+ (plus sign) Adds a plus sign to a positive result, a minus sign to a negative result, or a space if the result is 0 (zero).
other symbol(s) Includes the specified character in the result.
‘text’ Adds text to the result. The text can contain any symbols, special symbols mentioned above are not interpreted.
“positive; negative; zero” You can use combinations for displaying positive, negative and zero values differently - just use a semicolon between switch arguments. For example, { MERGEFIELD Amount \# $#,##0.00;-$#,##0.00;$0 } displays positive values as $#,##0.00, negative values as -$#,##0.00, and zero values as $0.

Culture-Dependent Switches

When you use the RichEditDocumentServer library to open a template document with field codes that contain the decimal point and digit grouping symbol switches, the fields are parsed according to the current locale settings. Field codes and field results may change if the document template created on a machine with one local culture is opened on another locale.

You can use the RichEditMailMergeOptions.CustomSeparators property to specify group and decimal separators that are independent of the current culture settings.

The code sample below shows how to specify custom decimal separators for the field code and field result. In the MERGEFIELD field, the decimal separator is retrieved from the current ES-ES locale (the “,” (comma) symbol) instead of the “.” (dot) symbol specified in the field code. As a result, the field result is changed - the field displays a whole number, and the dot is used as a thousands separator. The RichEditMailMergeOptions.CustomSeparators options specify the dot as a decimal separator, which is displayed regardless of the culture settings.

Specify Custom Decimal Separators

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
//...

var bindingSource = new BindingSource();
bindingSource.DataSource = new
{
    Order = 10,
    Amount = 12345.678m,
};

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    // Access a document.
    Document document = wordProcessor.Document;

    // Specify the data source of the document.
    wordProcessor.Options.MailMerge.DataSource = bindingSource;

    // Specify the custom decimal separator for the field code.
    wordProcessor.Options.MailMerge.CustomSeparators.MaskDecimalSeparator = ".";

    // Specify the custom decimal separator for the field result.
    wordProcessor.Options.MailMerge.CustomSeparators.FieldResultDecimalSeparator = ".";

    // Create the "MERGEFIELD" field.
    document.Fields.Create(document.Range.Start, @"MERGEFIELD Amount \# 0.00 ");

    // Merge the document.
    wordProcessor.Document.MailMerge("output.docx", DocumentFormat.OpenXml);
}