A custom DateTime format string consists of one or more custom DateTime format specifiers, and that format string defines the text representation of aDateTime object that is produced by a formatting operation. Note that any string that is not a standard DateTime format string is interpreted as a customDateTime format string.
Custom DateTime Format Specifiers
The following table describes the custom DateTime format specifiers. For examples of the output produced by each format specifier, see Custom DateTime Format Strings Output Examples.
Format specifier | Description |
---|---|
d | Represents the day of the month as a number from 1 through 31. A single-digit day is formatted without a leading zero. For more information about using a single format specifier, see Using Single Custom Format Specifiers. |
dd | Represents the day of the month as a number from 01 through 31. A single-digit day is formatted with a leading zero. |
ddd | Represents the abbreviated name of the day of the week as defined in the currentSystem.Globalization.DateTimeFormatInfo.AbbreviatedDayNames property. |
dddd (plus any number of additional "d" specifiers) | Represents the full name of the day of the week as defined in the current System.Globalization.DateTimeFormatInfo.DayNames property. |
f | Represents the most significant digit of the seconds fraction. Note that if the "f" format specifier is used alone, without other format specifiers, it is interpreted as the "f" standard DateTime format specifier (full date/time pattern). For more information about using a single format specifier, see Using Single Custom Format Specifiers. When you use this format specifier with the ParseExact or TryParseExact method, the number of "f" format specifiers that you use indicates the number of most significant digits of the seconds fraction to parse. |
ff | Represents the two most significant digits of the seconds fraction. |
fff | Represents the three most significant digits of the seconds fraction. |
ffff | Represents the four most significant digits of the seconds fraction. |
fffff | Represents the five most significant digits of the seconds fraction. |
ffffff | Represents the six most significant digits of the seconds fraction. |
fffffff | Represents the seven most significant digits of the seconds fraction. |
F | Represents the most significant digit of the seconds fraction. Nothing is displayed if the digit is zero. For more information about using a single format specifier, see Using Single Custom Format Specifiers. When you use this format specifier with the ParseExact or TryParseExact method, the number of "F" format specifiers that you use indicates the maximum number of most significant digits of the seconds fraction to parse. |
FF | Represents the two most significant digits of the seconds fraction. However, trailing zeros, or two zero digits, are not displayed. |
FFF | Represents the three most significant digits of the seconds fraction. However, trailing zeros, or three zero digits, are not displayed. |
FFFF | Represents the four most significant digits of the seconds fraction. However, trailing zeros, or four zero digits, are not displayed. |
FFFFF | Represents the five most significant digits of the seconds fraction. However, trailing zeros, or five zero digits, are not displayed. |
FFFFFF | Represents the six most significant digits of the seconds fraction. However, trailing zeros, or six zero digits, are not displayed. |
FFFFFFF | Represents the seven most significant digits of the seconds fraction. However, trailing zeros, or seven zero digits, are not displayed. |
g or gg (plus any number of additional "g" specifiers) | Represents the period or era (A.D. for example). This specifier is ignored if the date to be formatted does not have an associated period or era string. For more information about using a single format specifier, see Using Single Custom Format Specifiers. |
h | Represents the hour as a number from 1 through 12, that is, the hour as represented by a 12-hour clock that counts the whole hours since midnight or noon. Consequently, a particular hour after midnight is indistinguishable from the same hour after noon. The hour is not rounded, and a single-digit hour is formatted without a leading zero. For example, given a time of 5:43, this format specifier displays "5". For more information about using a single format specifier, see Using Single Custom Format Specifiers. |
hh, hh (plus any number of additional "h" specifiers) | Represents the hour as a number from 01 through 12, that is, the hour as represented by a 12-hour clock that counts the whole hours since midnight or noon. Consequently, a particular hour after midnight is indistinguishable from the same hour after noon. The hour is not rounded, and a single-digit hour is formatted with a leading zero. For example, given a time of 5:43, this format specifier displays "05". |
H | Represents the hour as a number from 0 through 23, that is, the hour as represented by a zero-based 24-hour clock that counts the hours since midnight. A single-digit hour is formatted without a leading zero. |
HH, HH (plus any number of additional "H" specifiers) | Represents the hour as a number from 00 through 23, that is, the hour as represented by a zero-based 24-hour clock that counts the hours since midnight. A single-digit hour is formatted with a leading zero. |
K | Represents different values of the DateTime.Kind property, that is, Local, Utc, or Unspecified. This specifier round-trips the kind value in text and preserves the time zone. For the Local kind value, this specifier is equivalent to the "zzz" specifier and displays the local offset, for example, "-07:00". For the Utc kind value, the specifier displays a "Z" character to represent a UTC date. For the Unspecified kind value, the specifier is equivalent to "" (nothing). |
m | Represents the minute as a number from 0 through 59. The minute represents whole minutes passed since the last hour. A single-digit minute is formatted without a leading zero. For more information about using a single format specifier, see Using Single Custom Format Specifiers. |
mm, mm (plus any number of additional "m" specifiers) | Represents the minute as a number from 00 through 59. The minute represents whole minutes passed since the last hour. A single-digit minute is formatted with a leading zero. |
M | Represents the month as a number from 1 through 12. A single-digit month is formatted without a leading zero. For more information about using a single format specifier, see Using Single Custom Format Specifiers. |
MM | Represents the month as a number from 01 through 12. A single-digit month is formatted with a leading zero. |
MMM | Represents the abbreviated name of the month as defined in the current System.Globalization.DateTimeFormatInfo.AbbreviatedMonthNamesproperty. |
MMMM | Represents the full name of the month as defined in the current System.Globalization.DateTimeFormatInfo.MonthNames property. |
s | Represents the seconds as a number from 0 through 59. The second represents whole seconds passed since the last minute. A single-digit second is formatted without a leading zero. For more information about using a single format specifier, see Using Single Custom Format Specifiers. |
ss, ss (plus any number of additional "s" specifiers) | Represents the seconds as a number from 00 through 59. The second represents whole seconds passed since the last minute. A single-digit second is formatted with a leading zero. |
t | Represents the first character of the A.M./P.M. designator defined in the current System.Globalization.DateTimeFormatInfo.AMDesignator orSystem.Globalization.DateTimeFormatInfo.PMDesignator property. The A.M. designator is used if the hour in the time being formatted is less than 12; otherwise, the P.M. designator is used. For more information about using a single format specifier, see Using Single Custom Format Specifiers. |
tt, tt (plus any number of additional "t" specifiers) | Represents the A.M./P.M. designator as defined in the current System.Globalization.DateTimeFormatInfo.AMDesignator orSystem.Globalization.DateTimeFormatInfo.PMDesignator property. The A.M. designator is used if the hour in the time being formatted is less than 12; otherwise, the P.M. designator is used. |
y | Represents the year as at most a two-digit number. If the year has more than two digits, only the two low-order digits appear in the result. If the year has fewer than two digits, the number is formatted without a leading zero. For more information about using a single format specifier, seeUsing Single Custom Format Specifiers. |
yy | Represents the year as a two-digit number. If the year has more than two digits, only the two low-order digits appear in the result. If the year has fewer than two digits, the number is padded with leading zeroes to achieve two digits. |
yyy | Represents the year as a three-digit number. If the year has more than three digits, only the three low-order digits appear in the result. If the year has fewer than three digits, the number is padded with leading zeroes to achieve three digits. Note that for the Thai Buddhist calendar, which can have five-digit years, this format specifier displays all five digits. |
yyyy | Represents the year as a four-digit number. If the year has more than four digits, only the four low-order digits appear in the result. If the year has fewer than four digits, the number is padded with leading zeroes to achieve four digits. Note that for the Thai Buddhist calendar, which can have five-digit years, this format specifier renders all five digits. |
yyyyy (plus any number of additional "y" specifiers) | Represents the year as a five-digit number. If the year has more than five digits, only the five low-order digits appear in the result. If the year has fewer than five digits, the number is padded with leading zeroes to achieve five digits. If there are additional "y" specifiers, the number is padded with as many leading zeroes as necessary to achieve the number of "y" specifiers. |
z | Represents the signed time zone offset of your system from Greenwich Mean Time (GMT) measured in hours. For example, the offset for a computer in the Pacific Standard Time zone is "-8". The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of GMT and a minus sign (-) indicates hours behind GMT. The offset ranges from –12 through +13. A single-digit offset is formatted without a leading zero. The offset is affected by daylight savings time. For more information about using a single format specifier, see Using Single Custom Format Specifiers. |
zz | Represents the signed time zone offset of your system from Greenwich Mean Time (GMT) measured in hours. For example, the offset for a computer in the Pacific Standard Time zone is "-08". The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of GMT and a minus sign (-) indicates hours behind GMT. The offset ranges from –12 through +13. A single-digit offset is formatted with a leading zero. The offset is affected by daylight savings time. |
zzz, zzz (plus any number of additional "z" specifiers) | Represents the signed time zone offset of your system from Greenwich Mean Time (GMT) measured in hours and minutes. For example, the offset for a computer in the Pacific Standard Time zone is "-08:00". The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of GMT and a minus sign (-) indicates hours behind GMT. The offset ranges from –12 through +13. A single-digit offset is formatted with a leading zero. The offset is affected by daylight savings time. |
: | The time separator defined in the current System.Globalization.DateTimeFormatInfo.TimeSeparator property that is used to differentiate hours, minutes, and seconds. |
/ | The date separator defined in the current System.Globalization.DateTimeFormatInfo.DateSeparator property that is used to differentiate years, months, and days. |
" | Quoted string (quotation mark). Displays the literal value of any string between two quotation marks ("). Precede each quotation mark with an escape character (\). |
' | Quoted string (apostrophe). Displays the literal value of any string between two apostrophe (') characters. |
%c | Represents the result associated with a custom format specifier "c", when the custom DateTime format string consists solely of that custom format specifier. That is, to use the "d", "f", "F", "h", "m", "s", "t", "y", "z", "H", or "M" custom format specifier by itself, specify "%d", "%f", "%F", "%h", "%m", "%s", "%t", "%y", "%z", "%H", or "%M". For more information about using a single format specifier, see Using Single Custom Format Specifiers. |
\c | The escape character. Displays the character "c" as a literal when that character is preceded by the escape character (\). To insert the backslash character itself in the result string, use two escape characters ("\\"). |
Any other character | Any other character is copied to the result string, and does not affect formatting. |
Control Panel Settings
The settings in the Regional and Language Options item in Control Panel influence the result string produced by a formatting operation. Those settings are used to initialize the DateTimeFormatInfo object associated with the current thread culture, and the current thread culture provides values used to govern formatting. Computers using different settings will generate different result strings.
DateTimeFormatInfo Properties
Formatting is influenced by properties of the current DateTimeFormatInfo object, which is provided implicitly by the current thread culture or explicitly by theIFormatProvider parameter of the method that invokes formatting. Specify for the IFormatProvider parameter a CultureInfo object, which represents a culture, or aDateTimeFormatInfo object.
Many of the standard DateTime format specifiers are aliases for formatting patterns defined by properties of the current DateTimeFormatInfo object. This means you can change the result produced by some standard DateTime format specifiers by changing the corresponding DateTimeFormatInfo property.
Using Single Custom Format Specifiers
A custom DateTime format string consists of two or more characters. For example, if the format string consists only of the specifier "h", the format string is interpreted as a standard DateTime format string. However, in this particular case an exception is thrown because there is no "h" standard DateTime format specifier.
To use a single custom DateTime format specifier, include a space before or after the DateTime specifier, or include a percent (%) format specifier before theDateTime specifier. For example, the format strings "h " and "%h" are interpreted as custom DateTime format strings that display the hour represented by the current DateTime object. Note that if a space is used, it will appear as a literal character in the result string.
Using Custom Format Strings
The following code fragment illustrates how to create custom formatted strings from a DateTime object. This example assumes that the current culture is English-United States (en-US).
String MyString = MyDate.ToString("dddd - d - MMMM");
// In the U.S. English culture, MyString has the value:
// "Saturday - 1 - January".
MyString = MyDate.ToString("yyyy gg");
// In the U.S. English culture, MyString has the value: "2000 A.D.".
Example
The following code example demonstrates the result yielded by each custom DateTime format specifier.
// DateTime format specifier.
using System;
using System.Globalization;
class Sample
{
public static void Main()
{
string formatString;
CultureInfo ci = new CultureInfo("");
string msgDTctor = "The DateTime constructor for " +
"January 3, 0001 A.D., 02:09:20.444 P.M. is\n" +
" DateTime(0001, 1, 3, 14, 9, 20, 444)\n";
DateTime thisDate = new DateTime(0001, 1, 3, 14, 9, 20, 444); // This is equal to DateTime thisDate = new DateTime(0001, 1, 3, 14, 9, 20, 444, DateTime.Unspecified)
DateTime utcDate = new DateTime(0002, 2, 4, 15, 10, 21, 555, DateTimeKind.Utc);
DateTime localDate = new DateTime(0003, 3, 5, 16, 11, 22, 666, DateTimeKind.Local);
// Custom DateTime format specifiers
string[] specifiers = {
// Year
"%y",
"yy",
"yyy",
"yyyy",
"yyyyy",
// Month
"%M",
"MM",
"MMM",
"MMMM",
// Day
"%d",
"dd",
"ddd",
"dddd",
// Era
"%g",
"gg",
// Hour
"%h",
"hh",
"%H",
"HH",
// Minute
"%m",
"mm",
// Second
"%s",
"ss",
// Fraction of a second
"%f",
"ff",
"fff",
"ffff",
"fffff",
"ffffff",
"fffffff",
"%F",
"FF",
"FFF",
"FFFF",
"FFFFF",
"FFFFFF",
"FFFFFFF",
// A.M./P.M. designator
"%t",
"tt",
// UTC offset
"%z",
"zz",
"zzz",
// Quoted string (apostrophe)
"'The year is' yyyy",
// Quoted string (quotation mark)
"\"The year is\" yyyy",
// Escape character
@"\\",
};
//
Console.Clear();
Console.WriteLine("The culture is {0}.", ci.DisplayName);
Console.WriteLine(msgDTctor);
Console.WriteLine("{0,20} {1}", "Custom format string", "Yields");
Console.WriteLine("{0,20} {1}", "--------------------", "------");
foreach (string format in specifiers)
{
formatString = "\"" + format + "\"";
Console.WriteLine("{0,20} \"{1}\"",
formatString, thisDate.ToString(format));
}
Console.WriteLine();
Console.WriteLine();
// Example of using "K" format specifier.
Console.WriteLine("Format different kinds of DateTime using \"K\"");
Console.WriteLine("{0, 20} {1}", "DateTimeKind", "Yields");
Console.WriteLine("{0,20} {1}", "------------", "------");
Console.WriteLine("{0,20} \"{1}\"", thisDate.Kind, thisDate.ToString("%K"));
Console.WriteLine("{0,20} \"{1}\"", utcDate.Kind, utcDate.ToString("%K"));
Console.WriteLine("{0,20} \"{1}\"", localDate.Kind, localDate.ToString("%K"));
}
}
/*
This code example produces the following results:
The culture is Invariant Language (Invariant Country).
The DateTime constructor for January 3, 0001 A.D., 02:09:20.444 P.M. is
DateTime(0001, 1, 3, 14, 9, 20, 444)
Custom format string Yields
-------------------- ------
"%y" "1"
"yy" "01"
"yyy" "001"
"yyyy" "0001"
"yyyyy" "00001"
"%M" "1"
"MM" "01"
"MMM" "Jan"
"MMMM" "January"
"%d" "3"
"dd" "03"
"ddd" "Wed"
"dddd" "Wednesday"
"%g" "A.D."
"gg" "A.D."
"%h" "2"
"hh" "02"
"%H" "14"
"HH" "14"
"%m" "9"
"mm" "09"
"%s" "20"
"ss" "20"
"%f" "4"
"ff" "44"
"fff" "444"
"ffff" "4440"
"fffff" "44400"
"ffffff" "444000"
"fffffff" "4440000"
"%F" "4"
"FF" "44"
"FFF" "444"
"FFFF" "444"
"FFFFF" "444"
"FFFFFF" "444"
"FFFFFFF" "444"
"%t" "P"
"tt" "PM"
"%z" "-8"
"zz" "-08"
"zzz" "-08:00"
"'The year is' yyyy" "The year is 0001"
""The year is" yyyy" "The year is 0001"
"\\" "\"
Format different kinds of DateTime using "K"
DateTimeKind Yields
------------ ------
Unspecified ""
Utc "Z"
Local "-08:00"
*/
// Displays 29 agosto