DateTimeOffset.ToString
Method
Definition
Overloads
| ToString() |
Converts the value of the current DateTimeOffset object to its equivalent string representation. |
| ToString(IFormatProvider) |
Converts the value of the current DateTimeOffset object to its equivalent string representation using the specified culture-specific formatting information. |
| ToString(String) |
Converts the value of the current DateTimeOffset object to its equivalent string representation using the specified format. |
| ToString(String, IFormatProvider) |
Converts the value of the current DateTimeOffset object to its equivalent string representation using the specified format and culture-specific format information. |
ToString()
Converts the value of the current DateTimeOffset object to its equivalent string representation.
public override string ToString ();
A string representation of a DateTimeOffset object that includes the offset appended at the end of the string.
The date and time is outside the range of dates supported by the calendar used by the current culture.
Examples
The following example illustrates calls to the ToString() method and displays its output on a system whose current culture is en-us.
DateTimeOffset thisDate;
// Show output for UTC time
thisDate = DateTimeOffset.UtcNow;
Console.WriteLine(thisDate.ToString()); // Displays 3/28/2007 7:13:50 PM +00:00
// Show output for local time
thisDate = DateTimeOffset.Now;
Console.WriteLine(thisDate.ToString()); // Displays 3/28/2007 12:13:50 PM -07:00
// Show output for arbitrary time offset
thisDate = thisDate.ToOffset(new TimeSpan(-5, 0, 0));
Console.WriteLine(thisDate.ToString()); // Displays 3/28/2007 2:13:50 PM -05:00
Dim thisDate As DateTimeOffset
' Show output for UTC time
thisDate = DateTimeOffset.UtcNow
Console.WriteLine(thisDate.ToString()) ' Displays 3/28/2007 7:13:50 PM +00:00
' Show output for local time
thisDate = DateTimeOffset.Now
Console.WriteLine(thisDate.ToString()) ' Displays 3/28/2007 12:13:50 PM -07:00
' Show output for arbitrary time offset
thisDate = thisDate.ToOffset(new TimeSpan(-5, 0, 0))
Console.WriteLine(thisDate.ToString()) ' Displays 3/28/2007 2:13:50 PM -05:00
Remarks
The return value of this method is identical to that of the DateTime.ToString() method, except that it includes a space followed by the offset appended at the end of the string. In other words, it formats output using the short date pattern, the long time pattern, and the zzz custom format string, with each element separated from the previous element by a space. For example, if DateTime.ToString() returns a value of 1/12/2008 6:15:50 PM, ToString() returns a value of 1/12/2008 6:15:50 PM -08:00 for a time that is eight hours behind Coordinated Universal Time (UTC).
This method uses formatting information derived from the current culture. For more information, see CurrentCulture. Other overloads of the ToString method enable you to specify the culture whose formatting to use, and to define the output pattern of the DateTimeOffset value.
ToString(IFormatProvider)
Converts the value of the current DateTimeOffset object to its equivalent string representation using the specified culture-specific formatting information.
public string ToString (IFormatProvider formatProvider);
- formatProvider
- IFormatProvider
An object that supplies culture-specific formatting information.
A string representation of the value of the current DateTimeOffset object, as specified by formatProvider.
The date and time is outside the range of dates supported by the calendar used by formatProvider.
Examples
The following example displays a DateTimeOffset object using CultureInfo objects that represent the invariant culture, as well as four other cultures.
CultureInfo[] cultures = new CultureInfo[] {CultureInfo.InvariantCulture,
new CultureInfo("en-us"),
new CultureInfo("fr-fr"),
new CultureInfo("de-DE"),
new CultureInfo("es-ES")};
DateTimeOffset thisDate = new DateTimeOffset(2007, 5, 1, 9, 0, 0,
TimeSpan.Zero);
foreach (CultureInfo culture in cultures)
{
string cultureName;
if (string.IsNullOrEmpty(culture.Name))
cultureName = culture.NativeName;
else
cultureName = culture.Name;
Console.WriteLine("In {0}, {1}",
cultureName, thisDate.ToString(culture));
}
// The example produces the following output:
// In Invariant Language (Invariant Country), 05/01/2007 09:00:00 +00:00
// In en-US, 5/1/2007 9:00:00 AM +00:00
// In fr-FR, 01/05/2007 09:00:00 +00:00
// In de-DE, 01.05.2007 09:00:00 +00:00
// In es-ES, 01/05/2007 9:00:00 +00:00
Dim cultures() As CultureInfo = {CultureInfo.InvariantCulture, _
New CultureInfo("en-us"), _
New CultureInfo("fr-fr"), _
New CultureInfo("de-DE"), _
New CultureInfo("es-ES")}
Dim thisDate As New DateTimeOffset(#5/1/2007 9:00AM#, TimeSpan.Zero)
For Each culture As CultureInfo In cultures
Dim cultureName As String
If String.IsNullOrEmpty(culture.Name) Then
cultureName = culture.NativeName
Else
cultureName = culture.Name
End If
Console.WriteLine("In {0}, {1}", _
cultureName, thisDate.ToString(culture))
Next
' The example produces the following output:
' In Invariant Language (Invariant Country), 05/01/2007 09:00:00 +00:00
' In en-US, 5/1/2007 9:00:00 AM +00:00
' In fr-FR, 01/05/2007 09:00:00 +00:00
' In de-DE, 01.05.2007 09:00:00 +00:00
' In es-ES, 01/05/2007 9:00:00 +00:00
Remarks
The return value of this method is identical to that of its equivalent overload of the DateTime.ToString method, except that it includes a space followed by the offset appended at the end of the string. In other words, it formats output using the short date pattern, the long time pattern, and the zzz custom format string, with each element separated from the previous element by a space.
The format of these three elements is defined by the formatProvider parameter. The formatProvider parameter can be either of the following:
A CultureInfo object that represents the culture whose formatting conventions are applied to the returned string. The DateTimeFormatInfo object returned by the CultureInfo.DateTimeFormat property defines the formatting of the returned string.
A DateTimeFormatInfo object that defines the format of date and time data.
If formatProvider is null, the DateTimeFormatInfo object associated with the current culture is used (see CurrentCulture).
ToString(String)
Converts the value of the current DateTimeOffset object to its equivalent string representation using the specified format.
public string ToString (string format);
- format
- String
A format string.
A string representation of the value of the current DateTimeOffset object, as specified by format.
The length of format is one, and it is not one of the standard format specifier characters defined for DateTimeFormatInfo.
-or-
format does not contain a valid custom format pattern.
The date and time is outside the range of dates supported by the calendar used by the current culture.
Examples
The following example displays a DateTimeOffset object to the console using each of the standard date and time format specifiers. The output is formatted by using the en-us culture.
DateTimeOffset outputDate = new DateTimeOffset(2007, 10, 31, 21, 0, 0,
new TimeSpan(-8, 0, 0));
string specifier;
// Output date using each standard date/time format specifier
specifier = "d";
// Displays d: 10/31/2007
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "D";
// Displays D: Wednesday, October 31, 2007
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "t";
// Displays t: 9:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "T";
// Displays T: 9:00:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "f";
// Displays f: Wednesday, October 31, 2007 9:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "F";
// Displays F: Wednesday, October 31, 2007 9:00:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "g";
// Displays g: 10/31/2007 9:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "G";
// Displays G: 10/31/2007 9:00:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "M"; // 'm' is identical
// Displays M: October 31
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "R"; // 'r' is identical
// Displays R: Thu, 01 Nov 2007 05:00:00 GMT
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "s";
// Displays s: 2007-10-31T21:00:00
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
specifier = "u";
// Displays u: 2007-11-01 05:00:00Z
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
// Specifier is not supported
specifier = "U";
try
{
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
}
catch (FormatException)
{
Console.WriteLine("{0}: Not supported.", specifier);
}
specifier = "Y"; // 'y' is identical
// Displays Y: October, 2007
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier));
Dim outputDate As New DateTimeOffset(#10/31/2007 9:00PM#, _
New TimeSpan(-8, 0, 0))
Dim specifier As String
' Output date using each standard date/time format specifier
specifier = "d"
' Displays d: 10/31/2007
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "D"
' Displays D: Wednesday, October 31, 2007
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "t"
' Displays t: 9:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "T"
' Displays T: 9:00:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "f"
' Displays f: Wednesday, October 31, 2007 9:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "F"
' Displays F: Wednesday, October 31, 2007 9:00:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "g"
' Displays g: 10/31/2007 9:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "G"
' Displays G: 10/31/2007 9:00:00 PM
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "M" ' 'm' is identical
' Displays M: October 31
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "R" ' 'r' is identical
' Displays R: Thu, 01 Nov 2007 05:00:00 GMT
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "s"
' Displays s: 2007-10-31T21:00:00
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
specifier = "u"
' Displays u: 2007-11-01 05:00:00Z
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
' Specifier is not supported
specifier = "U"
Try
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
Catch e As FormatException
Console.WriteLine("{0}: Not supported.", specifier)
End Try
specifier = "Y" ' 'y' is identical
' Displays Y: October, 2007
Console.WriteLine("{0}: {1}", specifier, outputDate.ToString(specifier))
Remarks
The format parameter should contain either a single format specifier character (see Standard Date and Time Format Strings) or a custom format pattern (see Custom Date and Time Format Strings) that defines the format of the returned string. If format is a null or empty string (""), the DateTimeOffset value is output using the default format.
The following table shows the exact operation of certain format specifiers when used with DateTimeOffset, which differs from their behavior when used with DateTime.
| Existing format specifier | New behavior |
|---|---|
| "K" | Designed to round-trip a date and time. With DateTimeOffset, maps to "zzz" (the offset is always displayed with hours and minutes). Note that "K" is a custom format specifier; it cannot appear as the single character in format. |
| "U" | Not supported. |
| "r" | Converts the DateTimeOffset object to Coordinated Universal Time (UTC) and outputs it using the custom format string ddd, dd MMM yyyy HH:mm:ss GMT. |
| "u" | Converts the DateTimeOffset object to UTC and outputs it using the format yyyy-MM-dd HH:mm:ssZ. |
The remaining standard date and time format specifiers behave the same with the ToString(String) method as they do with the ToString method.
This method uses formatting information derived from the current culture. For more information, see CurrentCulture.
ToString(String, IFormatProvider)
Converts the value of the current DateTimeOffset object to its equivalent string representation using the specified format and culture-specific format information.
public string ToString (string format, IFormatProvider formatProvider);
- format
- String
A format string.
- formatProvider
- IFormatProvider
An object that supplies culture-specific formatting information.
A string representation of the value of the current DateTimeOffset object, as specified by format and provider.
The length of format is one, and it is not one of the standard format specifier characters defined for DateTimeFormatInfo.
-or-
format does not contain a valid custom format pattern.
The date and time is outside the range of dates supported by the calendar used by formatProvider.
Examples
The following example uses the ToString(String, IFormatProvider) method to display a DateTimeOffset object using a custom format string for several different cultures.
DateTimeOffset outputDate = new DateTimeOffset(2007, 11, 1, 9, 0, 0,
new TimeSpan(-7, 0, 0));
string format = "dddd, MMM dd yyyy HH:mm:ss zzz";
// Output date and time using custom format specification
Console.WriteLine(outputDate.ToString(format, null as DateTimeFormatInfo));
Console.WriteLine(outputDate.ToString(format, CultureInfo.InvariantCulture));
Console.WriteLine(outputDate.ToString(format,
new CultureInfo("fr-FR")));
Console.WriteLine(outputDate.ToString(format,
new CultureInfo("es-ES")));
// The example displays the following output to the console:
// Thursday, Nov 01 2007 09:00:00 -07:00
// Thursday, Nov 01 2007 09:00:00 -07:00
// jeudi, nov. 01 2007 09:00:00 -07:00
// jueves, nov 01 2007 09:00:00 -07:00
Dim outputDate As New DateTimeOffset(#11/1/2007 9:00AM#, _
New TimeSpan(-7, 0, 0))
Dim format As String = "dddd, MMM dd yyyy HH:mm:ss zzz"
' Output date and time using custom format specification
Console.WriteLine(outputDate.ToString(format, Nothing))
Console.WriteLine(outputDate.ToString(format, CultureInfo.InvariantCulture))
Console.WriteLine(outputDate.ToString(format, _
New CultureInfo("fr-FR")))
Console.WriteLine(outputDate.ToString(format, _
New CultureInfo("es-ES")))
' The example displays the following output to the console:
' Thursday, Nov 01 2007 09:00:00 -07:00
' Thursday, Nov 01 2007 09:00:00 -07:00
' jeudi, nov. 01 2007 09:00:00 -07:00
' jueves, nov 01 2007 09:00:00 -07:00
Remarks
The format parameter should contain either a single format specifier character (see Standard Date and Time Format Strings) or a custom format pattern (see Custom Date and Time Format Strings). If format is a null or empty string (""), the DateTimeOffset object is output using the default format.
The following table shows the exact operation of certain format specifiers when used with DateTimeOffset, which differs from their behavior when used with DateTime.
| Existing format specifier | New behavior |
|---|---|
| "K" | Designed to round-trip a date and time. With DateTimeOffset, maps to "zzz" (the offset is always displayed with hours and minutes). Note that "K" is a custom format specifier; it cannot appear as the single character in format. |
| "U" | Not supported. |
| "r" | Converts the DateTimeOffset object to Coordinated Universal Time (UTC) and outputs it using the custom format string ddd, dd MMM yyyy HH:mm:ss GMT. |
| "u" | Converts the DateTimeOffset value to UTC and outputs it using the format yyyy-MM-dd HH:mm:ssZ. |
The remaining standard date and time format specifiers behave the same with the ToString(String) method as they do with the ToString method.
The pattern that corresponds to standard format specifiers, as well as the symbols and names of date and time components, is defined by the formatProvider parameter. The formatProvider parameter can be either of the following:
A CultureInfo object that represents the culture whose formatting is used in
input. The DateTimeFormatInfo object returned by the CultureInfo.DateTimeFormat property defines the formatting used ininput.A DateTimeFormatInfo object that defines the format of date and time data.
If formatProvider is null, the DateTimeFormatInfo object associated with the current culture is used (see CurrentCulture).