Format Specifiers
- 9 minutes to read
Format specifiers are symbols that specify the way data is formatted during its conversion to a string. This topic describes frequently used standard and custom format specifiers used to format numeric and date/time values.
To add custom text to the output string, you may choose between custom format specifiers (when formatting numeric or date/time values) and the composite formatting feature (when formatting any value).
General
If numeric values need to be formatted, set the FormatInfo.FormatType property to FormatType.Numeric. To format date/time values, set this property to FormatType.DateTime. Then, use the FormatInfo.FormatString property to specify a standard or custom format string.
Standard Format Strings for Numeric Values
Standard format strings for numeric values are specified in the Axx format. In this format, A is a character called the format specifier. xx is a sequence of optional digits called the precision specifier. The format specifier denotes whether values should be transformed into currency format, scientific notation, etc. This specifier must be set to one of the predefined characters listed in the following topic in MSDN: Standard Numeric Format Strings.
The following table gives several examples.
| Format Specifier | Description | Sample Format String | Sample Output |
|---|---|---|---|
| c or C | Converts the given number into a string that displays a currency amount. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default currency precision from the current locale is used. | c2 | $1,234.00 |
| e or E | Converts the given number into a string of the “-d.ddd…E+ddd” or “-d.ddd…e+ddd” form, in which each ‘d’ indicates a digit (0-9). The string begins with a minus sign if the number is negative. One digit always precedes the decimal point. The precision specifier indicates the desired number of digits after the decimal point. If the precision specifier is omitted, a default of six digits after the decimal point will be used. The format specifier indicates whether to prefix the exponent with an ‘E’ or an ‘e’. The exponent always consists of a plus or minus sign, and a minimum of three digits. The exponent is padded with zeros to meet this minimum if required. | E1 | 1.2E+003 |
| n or N | Converts the given number into a string of the “-d,ddd,ddd.ddd…” form, in which each ‘d’ indicates a digit (0-9). The string begins with a minus sign if the number is negative. Thousand separators are inserted between each group of three digits to the left of the decimal point. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default currency precision from the current regional options is used. | n0 | 1,234 |
| x or X | Converts the given number into a string of hexadecimal digits. The case of the format specifier indicates whether uppercase or lowercase characters are used for hexadecimal digits greater than 9. The precision specifier indicates the minimum number of digits in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier. This format is supported for integral types only. | X8 | 000004D2 |
Standard Format Strings for Date/Time Values
Standard date and time format strings contain a single character. This character defines the pattern used to display the value (if and how to display year numbers, month numbers, etc.).
All specifiers are explained in the Standard Date and Time Format Strings topic on MSDN. The following table includes a few examples:
| Format Specifier | Description | Sample Output |
|---|---|---|
| d | Short date pattern | 3/12/2003 |
| D | Long date pattern | Wednesday, March 12, 2003 |
| t | Short time pattern | 12:00 AM |
| T | Long time pattern | 12:00:00 AM |
| f | Full date/time pattern (short time) | Wednesday, March 12, 2003 12:00 AM |
| F | Full date/time pattern (full time) | Wednesday, March 12, 2003 12:00:00 AM |
| g | General date/time pattern (short time) | 3/12/2003 12:00 AM |
| G | General date/time pattern (full time) | 3/12/2003 12:00:00 AM |
Example 1
The following code demonstrates how to format values in a DateEdit control using the Long Date pattern.
The result for the English (US) culture is displayed below.
using DevExpress.Utils;
// ...
dateEdit1.Properties.DisplayFormat.FormatType = FormatType.DateTime;
dateEdit1.Properties.DisplayFormat.FormatString = "D";
Standard Format Strings for TimeSpanEdit Values
Standard TimeSpanEdit format strings contain a single character that defines the format specifier used to display the value (if and how to display year numbers, month numbers, etc.).
The following table lists the standard date time format specifiers used for the TimeSpanEdit control:
Format Specifier | Description | Sample Output |
|---|---|---|
d and D | Date/time format. It is not culture-sensitive. The t and T, f and F format specifiers’ behavior is identical to the d. Formats take the form [-][d.]hh:mm:ss | 1.5:25:30 |
g | General short format. This culture-sensitive format outputs the compact form of a TimeSpanEdit value. The format has the form [-][d:]h:mm:ss | 1:5:25:30 |
G | General long format. This culture-sensitive format outputs the long form of a TimeSpanEdit value (days and seven fractional digits). The format takes the form [-]d:hh:mm:ss.fffffff | 1:05:25:30.0000000 |
Custom Format Strings for Numeric Values
Custom format strings are used to construct format patterns manually. You only need to use custom formatting when the standard format strings do not meet your requirements. All format strings that consist of a literal character, followed by one or two digits, are treated as standard format strings, and thus all other strings are interpreted as custom format strings. The table below lists the most frequently used characters that can construct a custom format string. Please refer to the following topic in MSDN for a complete list of available characters: Custom Numeric Format Strings.
| Character | Meaning |
|---|---|
| 0 | The digit is always displayed. |
| # | The digit is displayed only when needed (used to suppress leading zeros). |
| . | Specifies the position of the decimal point. The appearance of the point depends on regional settings. |
| , | Specifies the position of a comma. The appearance of the comma depends on regional settings. |
Note that custom format strings may also contain other characters that will be copied to the formatted string. This can be used to add explanatory text to the value. If you need to display one of the reserved characters, it must be preceded by the ‘' symbol.
When formatting numeric values, you can apply different formats to positive, negative and zero values. To do this, the format string must contain three parts delimited by semicolons. The first part sets the format for positive values, the second applies the format for negative values, and the third specifies the format for zero values.
Example 2
The following example shows how to provide different formats for positive and negative numeric values and the zero value in a CalcEdit editor.
The result is demonstrated in the image below.
using DevExpress.Utils;
// ...
calcEdit1.Properties.DisplayFormat.FormatType = FormatType.Numeric;
calcEdit1.Properties.DisplayFormat.FormatString = "#.00;[#.0];Zero";
Custom Format Strings for Date/Time Values
To create format patterns for date and time values, combine the strings listed in the tables below. These strings represent the year, month, day, number and so on, in different formats.
The following table lists the most frequently used strings that can be used to format dates.
| Symbol | Meaning | Result of formatting a sample value (9/2/2003) |
|---|---|---|
| yy | The last two digits of the year. | 03 |
| yyyy | A four-digit year. | 2003 |
| MM | The number of the month. | 09 |
| MMM | A short text description of the month. | Sep |
| MMMM | The full name of the month. | September |
| dd | The number of the day. | 02 |
| ddd | A short text for the day of the week. | Tue |
| dddd | The full name of the day of the week. | Tuesday |
| / | Date separator. Its appearance depends on regional settings. |
The next table lists strings that are used to format time values.
| Symbol | Meaning |
|---|---|
| hh | Hours |
| mm | Minutes |
| ss | Seconds |
| tt | If present, represents data in AM/PM format |
| : | Time separator; its appearance depends upon regional settings |
Note
The tables above list only the most frequently used format strings. For the complete list, refer to the Custom Date and Time Format Strings topic in MSDN.
Example 3
The following sample code demonstrates a way of formatting date/time values in a DateEdit control using a custom format string.
using DevExpress.Utils;
// ...
dateEdit1.Properties.DisplayFormat.FormatType = FormatType.DateTime;
dateEdit1.Properties.DisplayFormat.FormatString = "MMM/d/yyyy hh:mm tt";
Custom Format Strings for TimeSpanEdit Values
To create a custom format string for TimeSpanEdit values, combine date and time format specifiers listed in the tables below.
See the Custom TimeSpan Format Strings topic in MSDN for the complete list of specifiers.
The following table lists the most frequently used strings that can be used to format date and time values:
Format specifier | Description | Result of formatting a sample value (1 day, 5 hours, 25 minutes, 30 seconds) |
|---|---|---|
d, %d | The number of days in the interval. | 1 |
dd-dddddddd | The number of days with leading zeros for single- or double-digit days. | 01-00000001 |
h, %h | The number of whole hours that are not included as part of days without a leading zero. | 5 |
hh | The number of whole hours that are not included as part of days with a leading zero. | 05 |
m, %m | The number of whole minutes that are not included as part of hours without a leading zero. | 25 |
mm | The number of whole minutes that are not included as part of hours with a leading zero. | 25 |
s, %s | The number of whole seconds that are not included as part of minutes without a leading zero. | 30 |
ss | The number of whole seconds that are not included as part of minutes with a leading zero. | 30 |
The following sample code illustrates how to format the specified time span value in a TimeSpanEdit control using a custom format string:
using DevExpress.Utils;
// ...
timeSpanEdit1.TimeSpan = new TimeSpan(1, 5, 25, 30);
timeSpanEdit1.Properties.DisplayFormat.FormatString =
"{0:dd} days, {0:%h} hours, {0:%m} minutes, {0:ss} seconds";
