Apostate Café


By joshua

Pubished:

Posted in: programming

String format specifiers for .Net

String format specifiers for .Net
Using .NET Format Strings ========================= Data formatting in the .NET framework follows conventions similar to those of Visual Basic, but there are some differences. First, the system Regional Options influence the results of format specifiers. In addition, with the exception of some invariant culture specifiers, the separators used to parse format strings can vary based on the specified format provider. Format strings can often be used on a .ToString() call, when using a StringBuilder, or for specifying data display format for many data-related controls. Standard DateTime Format Strings ———————————————— A standard **DateTime** format string consists of a single format specifier character from the following table. If the format specifier is not found in the table below, a runtime exception is thrown. If the format string is longer than a single character (even if the extra characters are white spaces), the format string is interpreted as a custom format string. Note that the result string produced by these format specifiers are influenced by the settings in the Regional Options control panel. Computers with different cultures or different date and time settings will generate different result strings. The date and time separators displayed by format strings are defined by the *DateSeparator* and *TimeSeparator* characters associated with the *DateTimeFormat* property of the current culture. However, in cases where the *InvariantCulture* is referenced by the ‘r’, ‘s’, and ‘u’ specifiers, the characters associated with the **DateSeparator** and **TimeSeparator**characters do not change based on the current culture. The following table describes the standard format specifiers for formatting the **DateTime**object. Standard format specifiers display the data in some established format, and are speified by the single-character standard format specifier. These are different than *custom* format strings.
Format specifier Name Description
d Short date pattern Displays a pattern defined by the **DateTimeFormatInfo.ShortDatePattern** property associated with the current thread or by a specified format provider. ~~~~ {.codesamp} DateTime.ToString(“d”) Sample Output: 1/4/2003 ~~~~
D Long date pattern Displays a pattern defined by the **DateTimeFormatInfo.LongDatePattern** property associated with the current thread or by a specified format provider. ~~~~ {.codesamp} DateTime.ToString(“D”) Sample Output: Saturday, January 04, 2003 ~~~~
t Short time pattern Displays a pattern defined by the **DateTimeFormatInfo.ShortTimePattern** property associated with the current thread or by a specified format provider.

~~~~ {.codesamp} DateTime.ToString(“t”) Sample Output: 8:09 AM ~~~~

T Long time pattern Displays a pattern defined by the **DateTimeFormatInfo.LongTimePattern** property associated with the current thread or by a specified format provider. ~~~~ {.codesamp} DateTime.ToString(“T”) Sample Output: 8:09:07 AM ~~~~
f Full date/time pattern (short time) Displays a combination of the long date and short time patterns, separated by a space. ~~~~ {.codesamp} DateTime.ToString(“f”) Sample Output: Saturday, January 04, 2003 8:09 AM ~~~~
F Full date/time pattern (long time) Displays a pattern defined by the **DateTimeFormatInfo.FullDateTimePattern** property associated with the current thread or by a specified format provider.

~~~~ {.codesamp} DateTime.ToString(“F”) Sample Output: Saturday, January 04, 2003 8:09:07 AM ~~~~

g General date/time pattern (short time) Displays a combination of the short date and short time patterns, separated by a space. ~~~~ {.codesamp} DateTime.ToString(“g”) Sample Output: 1/4/2003 8:09 AM ~~~~
G General date/time pattern (long time) Displays a combination of the short date and long time patterns, separated by a space. ~~~~ {.codesamp} DateTime.ToString(“G”) Sample Output: 1/4/2003 8:09:07 AM ~~~~
M or m Month day pattern Displays a pattern defined by the **DateTimeFormatInfo.MonthDayPattern** property associated with the current thread or by a specified format provider. ~~~~ {.codesamp} DateTime.ToString(“M”) Sample Output: January 04 ~~~~
R or r RFC1123 pattern Displays a pattern defined by the **DateTimeFormatInfo.RFC1123Pattern** property associated with the current thread or by a specified format provider. This is a defined standard and the property is read-only; therefore, it is always the same regardless of the culture used, or the format provider supplied. The property references the **CultureInfo.InvariantCulture** property and follows the custom pattern “ddd, dd MMM yyyy HH:mm:ss G\MT”. Note that the ‘M’ in “GMT” needs an escape character so it is not interpreted. Formatting does not modify the value of the **DateTime**; therefore, you must adjust the value to GMT before formatting. ~~~~ {.codesamp} DateTime.ToString(“R”) Sample Output: Sat, 04 Jan 2003 08:09:07 GMT ~~~~
s Sortable date/time pattern; conforms to ISO 8601 Displays a pattern defined by the **DateTimeFormatInfo.SortableDateTimePattern** property associated with the current thread or by a specified format provider. The property references the **CultureInfo.InvariantCulture** property, and the format follows the custom pattern “yyyy-MM-ddTHH:mm:ss”. ~~~~ {.codesamp} DateTime.ToString(“s”) Sample Output: 2003-01-04T08:09:07 ~~~~
u Universal sortable date/time pattern Displays a pattern defined by the **DateTimeFormatInfo.UniversalSortableDateTimePattern** property associated with the current thread or by a specified format provider. Because it is a defined standard and the property is read-only, the pattern is always the same regardless of culture or format provider. Formatting follows the custom pattern “yyyy-MM-dd HH:mm:ssZ”. No time zone conversion is done when the date and time is formatted; therefore, convert a local date and time to universal time before using this format specifier. ~~~~ {.codesamp} DateTime.ToString(“u”) Sample Output: 2003-01-04 08:09:07Z ~~~~
U Universal sortable date/time pattern Displays a pattern defined by the **DateTimeFormatInfo.FullDateTimePattern** property associated with the current thread or by a specified format provider. Note that the time displayed is for the universal, rather than local time. ~~~~ {.codesamp} DateTime.ToString(“U”) Sample Output: Saturday, January 04, 2003 2:09:07 PM ~~~~
Y or y Year month pattern Displays a pattern defined by the **DateTimeFormatInfo.YearMonthPattern** property associated with the current thread or by a specified format provider.

~~~~ {.codesamp} DateTime.ToString(“Y”) Sample Output: January, 2003 ~~~~

Any other single character Unknown specifier Throws a **System.FormatException** exception. ~~~~ {.codesamp} DateTime.ToString(“X”) Sample Output: Unhandled Exception: System.FormatException: Input string was not in a correct format. at System.DateTimeFormat.GetRealFormat(String format, DateTimeFormatInfo dtfi) at System.DateTimeFormat.ExpandPredefinedFormat(String format, DateTime& dateTime, DateTimeFormatInfo& dtfi) at System.DateTimeFormat.Format(DateTime dateTime, String format, DateTimeFormatInfo dtfi) at System.DateTime.ToString(String format, IFormatProvider provider) ~~~~
Custom DateTime Format Strings ——————————————— As opposed to *Standard* format specifiers, custom format strings allow greater control over how a **DateTime** is formatted. The following table describes the custom format specifiers and the results they produce. The output of these format specifiers is influenced by the current culture and the settings in the Regional Options control panel.
Format specifier Description
d Displays the current day of the month, measured as a number between 1 and 31, inclusive. If the day is a single digit only (1-9), then it is displayed as a single digit.

Note that if the ‘d’ format specifier is used alone, without other custom format strings, it is interpreted as the standard short date pattern format specifier. If the ‘d’ format specifier is passed with other custom format specifiers or the ‘%’ character, it is interpreted as a custom format specifier.
dd Displays the current day of the month, measured as a number between 1 and 31, inclusive. If the day is a single digit only (1-9), it is formatted with a preceding 0 (01-09).
ddd Displays the abbreviated name of the day for the specified **DateTime**. If a specific valid format provider (a non-null object that implements **IFormatProvider** with the expected property) is not supplied, then the **AbbreviatedDayNames** property of the

**DateTimeFormat** and its current culture associated with the current thread is used. Otherwise, the **AbbreviatedDayNames** property from the specified format provider is used.

dddd (plus any number of additional “d” characters) Displays the full name of the day for the specified **DateTime**. If a specific valid format provider (a non-null object that implements **IFormatProvider** with the expected property) is not supplied, then the **DayNames** property of the **DateTimeFormat**

and its current culture associated with the current thread is used. Otherwise, the **DayNames** property from the specified format provider is used.

f Displays seconds fractions represented in one digit.

Note that if the ‘f’ format specifier is used alone, without other custom format strings, it is interpreted as the full (long date + short time) format specifier. If the ‘f’ format specifier is passed with other custom format specifiers or the ‘%’ character, it is interpreted as a custom format specifier.
ff Displays seconds fractions represented in two digits.
fff Displays seconds fractions represented in three digits.
ffff Displays seconds fractions represented in four digits.
fffff Displays seconds fractions represented in five digits.
ffffff Displays seconds fractions represented in six digits.
fffffff Displays seconds fractions represented in seven digits.
g or gg (plus any number of additional “g” characters) Displays the era (A.D. for example) for the specified **DateTime**. If a specific valid format provider (a non-null object that implements **IFormatProvider** with the expected property) is not supplied, then the era is determined from the calendar associated with the **DateTimeFormat** and its current culture associated with the current thread. Note that if the ‘g’ format specifier is used alone, without other custom format strings, it is interpreted as the standard general format specifier. If the ‘g’ format specifier is passed with other custom format specifiers or the ‘%’ character, it is interpreted as a custom format specifier.
h Displays the hour for the specified **DateTime** in the range 1-12. The hour represents whole hours passed since either midnight (displayed as 12) or noon (also displayed as 12). If this format is used alone, then the same hour before or after noon is indistinguishable. If the hour is a single digit (1-9), it is displayed as a single digit. No rounding occurs when displaying the hour. For example, a **DateTime** of 5:43 returns 5.
hh, hh (plus any number of additional “h” characters) Displays the hour for the specified **DateTime** in the range 1-12. The hour represents whole hours passed since either midnight (displayed as 12) or noon (also displayed as 12). If this format is used alone, then the same hour before or after noon is indistinguishable. If the hour is a single digit (1-9), it is formatted with a preceding 0 (01-09).
H Displays the hour for the specified **DateTime** in the range 0-23. The hour represents whole hours passed since midnight (displayed as 0). If the hour is a single digit (0-9), it is displayed as a single digit.
HH, HH (plus any number of additional “H” characters) Displays the hour for the specified **DateTime** in the range 0-23. The hour represents whole hours passed since midnight (displayed as 0). If the hour is a single digit (0-9), it is formatted with a preceding 0 (01-09).
m Displays the minute for the specified **DateTime** in the range 0-59. The minute represents whole minutes passed since the last hour. If the minute is a single digit (0-9), it is displayed as a single digit. Note that if the ‘m’ format specifier is used alone, without other custom format strings, it is interpreted as the standard month day pattern format specifier. If the ‘m’ format specifier is passed with other custom format specifiers or the ‘%’ character, it is interpreted as a custom format specifier.
mm, mm (plus any number of additional “m” characters) Displays the minute for the specified **DateTime** in the range 0-59. The minute represents whole minutes passed since the last hour. If the minute is a single digit (0-9), it is formatted with a preceding 0 (01-09).
M Displays the month, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is displayed as a single digit. Note that if the ‘M’ format specifier is used alone, without other custom format strings, it is interpreted as the standard month day pattern format specifier. If the ‘M’ format specifier is passed with other custom format specifiers or the ‘%’ character, it is interpreted as a custom format specifier.
MM Displays the month, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is formatted with a preceding 0 (01-09).
MMM Displays the abbreviated name of the month for the specified **DateTime**. If a specific valid format provider (a non-null object that implements **IFormatProvider** with the expected property) is not supplied, the **AbbreviatedMonthNames** property of the

**DateTimeFormat** and its current culture associated with the current thread is used. Otherwise, the **AbbreviatedMonthNames** property from the specified format provider is used.

MMMM Displays the full name of the month for the specified **DateTime**. If a specific valid format provider (a non-null object that implements **IFormatProvider** with the expected property) is not supplied, then the **MonthNames** property of the **DateTimeFormat**

and its current culture associated with the current thread is used. Otherwise, the **MonthNames** property from the specified format provider is used.

s Displays the seconds for the specified **DateTime** in the range 0-59. The second represents whole seconds passed since the last minute. If the second is a single digit (0-9), it is displayed as a single digit only. Note that if the ‘s’ format specifier is used alone, without other custom format strings, it is interpreted as the standard sortable date/time pattern format specifier. If the ‘s’ format specifier is passed with other custom format specifiers or the ‘%’ character, it is interpreted as a custom format specifier.
ss, ss (plus any number of additional “s” characters) Displays the seconds for the specified **DateTime** in the range 0-59. The second represents whole seconds passed since the last minute. If the second is a single digit (0-9), it is formatted with a preceding 0 (01-09).
t Displays the first character of the A.M./P.M. designator for the specified **DateTime**. If a specific valid format provider (a non-null object that implements **IFormatProvider** with the expected property) is not supplied, then the **AMDesignator** (or

**PMDesignator**) property of the **DateTimeFormat** and its current culture associated with the current thread is used. Otherwise, the **AMDesignator** (or **PMDesignator**) property from the specified **IFormatProvider** is used. If the total number of whole hours passed for the specified **DateTime** is less than 12, then the **AMDesignator** is used. Otherwise, the **PMDesignator** is used. Note that if the ‘t’ format specifier is used alone, without other custom format strings, it is interpreted as the standard long time pattern format specifier. If the ‘t’ format specifier is passed with other custom format specifiers or the ‘%’ character, it is interpreted as a custom format specifier.
tt, tt (plus any number of additional “t” characters) Displays the A.M./P.M. designator for the specified **DateTime**. If a specific valid format provider (a non-null object that implements **IFormatProvider** with the expected property) is not supplied, then the **AMDesignator** (or **PMDesignator**) property of the **DateTimeFormat** and its current culture associated with the current thread is used. Otherwise, the **AMDesignator** (or

**PMDesignator**) property from the specified **IFormatProvider** is used. If the total number of whole hours passed for the specified **DateTime** is less than 12, then the **AMDesignator** is used. Otherwise, the **PMDesignator** is used.

y Displays the year for the specified **DateTime** as a maximum two-digit number. The first two digits of the year are omitted. If the year is a single digit (1-9), it is displayed as a single digit.

Note that if the ‘y’ format specifier is used alone, without other custom format strings, it is interpreted as the standard short date pattern format specifier. If the ‘y’ format specifier is passed with other custom format specifiers or the ‘%’ character, it is interpreted as a custom format specifier.
yy Displays the year for the specified **DateTime** as a maximum two-digit number. The first two digits of the year are omitted. If the year is a single digit (1-9), it is formatted with a preceding 0 (01-09).
yyyy Displays the year for the specified **DateTime**, including the century. If the year is less than four digits in length, then preceding zeros are appended as necessary to make the displayed year four digits long.
z Displays the time zone offset for the system’s current time zone in whole hours only. The offset is always displayed with a leading sign (zero is displayed as “+0”), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is displayed as a single digit with the appropriate leading sign. The setting for the time zone is specified as +X or –X where X is the offset in hours from GMT. The displayed offset is affected by daylight savings time.
zz Displays the time zone offset for the system’s current time zone in whole hours only. The offset is always displayed with a leading or trailing sign (zero is displayed as “+00”), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is formatted with a preceding 0 (01-09) with the appropriate leading sign. The setting for the time zone is specified as +X or –X where X is the offset in hours from GMT. The displayed offset is affected by daylight savings time.
zzz, zzz (plus any number of additional “z” characters) Displays the time zone offset for the system’s current time zone in hours and minutes. The offset is always displayed with a leading or trailing sign (zero is displayed as “+00:00”), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12:00 to +13:00. If the offset is a single digit (0-9), it is formatted with a preceding 0 (01-09) with the appropriate leading sign. The setting for the time zone is specified as +X or –X where X is the offset in hours from GMT. The displayed offset is affected by daylight savings time.
: Time separator.
/ Date separator.
Quoted string. Displays the literal value of any string between two quotation marks preceded by the escape character (/).
Quoted string. Displays the literal value of any string between two ” ‘ ” characters.
%*c* Where *c* is both a standard format specifier and a custom format specifier, displays the custom format pattern associated with the format specifier. Note that if a format specifier is used alone as a single character, it is interpreted as a standard format specifier. Only format specifiers consisting of two or more characters are interpreted as custom format specifiers. In order to display the custom format for a specifier defined as both a standard and a custom format specifier, precede the specifier with a % symbol.
\*c* Where *c* is any character, the escape character displays the next character as a literal. The escape character cannot be used to create an escape sequence (like “\n” for new line) in this context.
Any other character Other characters are written directly to the result string as literals.
DateTime Custom Format String Samples ——————————————————-
Format String Sample Output
dddd - d - MMMM ~~~~ {.codesamp} Saturday - 4 - January ~~~~
yyyy gg ~~~~ {.codesamp} 2003 A.D.~~~~
ddd, dd MMM yyyy HH:mm:ss G\MT ~~~~ {.codesamp} Sat, 04 Jan 2003 08:09:07 GMT ~~~~
yyyy-MM-dd HH:mm:ss ~~~~ {.codesamp} 2003-01-04 08:09:07 ~~~~
m/d/yy ~~~~ {.codesamp} 9/4/03 ~~~~
dddd, mmmm dd, yyyy ~~~~ {.codesamp} Saturday, 09 04, 2003 ~~~~
d-mmm ~~~~ {.codesamp} 4-09 ~~~~
mmmm-yy ~~~~ {.codesamp} 09-03 ~~~~
d-mmmm h:mm ~~~~ {.codesamp} 4-09 8:09 ~~~~
d-mmmm-yy ~~~~ {.codesamp} 4-09-03 ~~~~
d mmmm ~~~~ {.codesamp} 4 09 ~~~~
mmmm yy ~~~~ {.codesamp} 09 03 ~~~~
m/d/yy h:mm ~~~~ {.codesamp} 9/4/03 8:09 ~~~~
hh:mm tt ~~~~ {.codesamp} 08:09 AM ~~~~
h:mm:ss t ~~~~ {.codesamp} 8:09:07 A ~~~~
h:m:s:f ~~~~ {.codesamp} 8:9:7:1 ~~~~
hh:mm:ss:fffff ~~~~ {.codesamp} 08:09:07:12300 ~~~~
### Credit *Most of this is a re-hash of the documentation available from Microsoft. But Microsoft has the documentation spread out in a number of loosely related entries, instead of being in one place.*