Format Specifiers
- 6 minutes to read
This topic describes the most used standard and custom format specifiers that can be used to format numeric and date-time values.
Note
Refer to the Format Specifiers topic for a complete list of formatting types.
To add custom text to the output string, use either custom format specifiers as described below (when formatting numeric or date-time values) or the composite formatting feature (when formatting any value).
Standard Format Strings for Numeric Values
Standard format strings for numeric values are specified in the Axx format. Here A is a character called the format specifier. xx is a sequence of digits called the precision specifier. The format specifier denotes whether values should be transformed to currency format, scientific notation, etc. This specifier must be set to one of the predefined characters listed in the Standard Numeric Format Strings topic. The table below gives some used values.
| Format Specifier | Description | Sample Format String | Sample Output |
|---|---|---|---|
| c or C | The number is converted to a string that represents 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 regional options is used. | c2 | $1,234.00 |
| e or E | The number is converted to a string of the form “-d.ddd…E+ddd” or “-d.ddd…e+ddd”, where each ‘d’ indicates a digit (0-9). The string starts 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 is used. The case of 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 | The number is converted to a string of the form “-d,ddd,ddd.ddd…”, where each ‘d’ indicates a digit (0-9). The string starts 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 | The number is converted to 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 |
| p or P | The number is multiplied by 100 and then converted to a string. The result is used as the editor’s value. For example, if the editor’s value is 0.15, the “15 %” string is displayed. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default numeric precision declared in the NumberFormat object is used. | P1 | 123,400.0% |
Standard Format Strings for Date-Time Values
Standard date and time format strings contain a single character. This character defines the pattern used to represent the value (whether and how to display year numbers, month numbers, etc). The table below lists the most used format characters. Please refer to the Standard Date and Time Format Strings topic in MSDN for a complete list.
| 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 |
Custom Format Strings for Numeric Values
Custom format strings are used to construct format patterns manually. You only need to use them when the standard format strings do not meet your requirements. All format strings represented by a literal character followed by one or two digits are treated as standard format strings and so all other strings are interpreted as custom format strings. The table below lists the most used characters that can construct a custom format string. Please refer to the Custom Numeric Format Strings topic in MSDN for a complete list of the characters available.
| Character | Meaning |
|---|---|
| 0 | The digit is always displayed. |
| # | The digit is displayed only when needed (i.e. use 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 can also contain other characters and they 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 positive values format, the second is applied to negative values and the third represents zero values.
Custom Format Strings for Date-Time Values
To create format patterns for date and time values, you need to 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 used strings that can be used to format dates. (Samples assume that the formatted date is 9/2/2003).
| Symbol | Meaning | Value |
|---|---|---|
| yy | The last two digits of the year. | 03 |
| yyyy | Four digit year. | 2003 |
| MM | The number of the month. | 09 |
| MMM | The short text description of the month. | Sep |
| MMMM | The full name of the month. | September |
| dd | The number of the day. | 02 |
| ddd | The 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 the regional settings. |
Note
The tables above list only the most used format string portions. Refer to the Custom Date and Time Format Strings for a complete list of date and time formatting types.