DateTime.ToString Method (String, IFormatProvider)
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
Converts the value of the current DateTime object to its equivalent string representation using the specified format and culture-specific format information.
Assembly: mscorlib (in mscorlib.dll)
'Declaration Public Function ToString ( _ format As String, _ provider As IFormatProvider _ ) As String
Parameters
- format
- Type: System.String
A standard or custom date and time format string (see Remarks).
- provider
- Type: System.IFormatProvider
An object that supplies culture-specific formatting information.
Return Value
Type: System.StringA string representation of value of the current DateTime object, as specified by the format and provider parameters.
Implements
IFormattable.ToString(String, IFormatProvider)| Exception | Condition |
|---|---|
| FormatException | The length of format is 1, and it is not one of the format specifier characters defined for DateTimeFormatInfo. -or- format does not contain a valid custom format pattern. |
| ArgumentOutOfRangeException | The date and time is outside the range of dates supported by the calendar used by provider. |
The format parameter can contain either a single format specifier character or a custom format pattern. If format is Nothing or an empty string (""), the standard format specifier, 'G', is used.
The provider parameter defines the pattern that corresponds to the standard format specifiers, as well as the symbols and names of date and time components. The provider parameter can be any of the following:
A CultureInfo object that represents the culture whose formatting conventions are to be reflected in 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.
A custom object that implements the IFormatProvider interface. Its GetFormat method returns a DateTimeFormatInfo object that provides formatting information.
If provider is Nothing, the DateTimeFormatInfo associated with the current culture is used. For more information, see CultureInfo.CurrentCulture.
Version Notes
Windows Phone
Windows Phone does not return the correct string for Russian dates. For example, 15.Июнь.2000 is returned instead of 15.июня.2000.The ToString(String, IFormatProvider) method returns the string representation of the date and time in the calendar used by the provider parameter. Its calendar is defined by the Calendar property. If the value of the current DateTime instance is earlier than Calendar.MinSupportedDateTime or later than Calendar.MaxSupportedDateTime, the method throws an ArgumentOutOfRangeException. The following example provides an illustration. It attempts to format a date that is outside the range of the UmAlQuraCalendar class.
Imports System.Globalization Module Example Public Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock) Dim arSA As New CultureInfo("ar-SA") arSA.DateTimeFormat.Calendar = New UmAlQuraCalendar() Dim date1 As Date = #9/10/1890# Try outputBlock.Text &= date1.ToString("d", arSA) & vbCrLf Catch e As ArgumentOutOfRangeException outputBlock.Text += String.Format("{0:d} is earlier than {1:d} or later than {2:d}", _ date1, _ arSA.DateTimeFormat.Calendar.MinSupportedDateTime, _ arSA.DateTimeFormat.Calendar.MaxSupportedDateTime) & vbCrLf End Try End Sub End Module ' The example displays the following output: ' 9/10/1890 is earlier than 4/30/1900 or later than 5/13/2029
The following example uses each of the standard date time format strings to display the string representation of a date and time for four different cultures.
Imports System.Globalization Module Example Public Sub Dcd emo(ByVal outputBlock As System.Windows.Controls.TextBlock) ' Create an array of all supported standard date and time format specifiers. Dim formats() As String = {"d", "D", "f", "F", "g", "G", "m", "o", "r", _ "s", "t", "T", "u", "U", "Y"} ' Create an array of four cultures. Dim cultures() As CultureInfo = {CultureInfo.CreateSpecificCulture("de-DE"), _ CultureInfo.CreateSpecificCulture("en-US"), _ CultureInfo.CreateSpecificCulture("es-ES"), _ CultureInfo.CreateSpecificCulture("fr-FR")} ' Define date to be displayed. Dim dateToDisplay As Date = #10/1/2008 5:04:32 PM# ' Iterate each standard format specifier. For Each formatSpecifier As String In formats For Each culture As CultureInfo In cultures outputBlock.Text += String.Format("{0} Format Specifier {1, 10} Culture {2, 40}", _ formatSpecifier, culture.Name, _ dateToDisplay.ToString(formatSpecifier, culture)) & vbCrLf Next outputBlock.Text &= vbCrLf Next End Sub End Module ' The example displays the following output: ' d Format Specifier de-DE Culture 01.10.2008 ' d Format Specifier en-US Culture 10/1/2008 ' d Format Specifier es-ES Culture 01/10/2008 ' d Format Specifier fr-FR Culture 01/10/2008 ' ' D Format Specifier de-DE Culture Mittwoch, 1. Oktober 2008 ' D Format Specifier en-US Culture Wednesday, October 01, 2008 ' D Format Specifier es-ES Culture miércoles, 01 de octubre de 2008 ' D Format Specifier fr-FR Culture mercredi 1 octobre 2008 ' ' f Format Specifier de-DE Culture Mittwoch, 1. Oktober 2008 17:04 ' f Format Specifier en-US Culture Wednesday, October 01, 2008 5:04 PM ' f Format Specifier es-ES Culture miércoles, 01 de octubre de 2008 17:04 ' f Format Specifier fr-FR Culture mercredi 1 octobre 2008 17:04 ' ' F Format Specifier de-DE Culture Mittwoch, 1. Oktober 2008 17:04:32 ' F Format Specifier en-US Culture Wednesday, October 01, 2008 5:04:32 PM ' F Format Specifier es-ES Culture miércoles, 01 de octubre de 2008 17:04:3 ' F Format Specifier fr-FR Culture mercredi 1 octobre 2008 17:04:32 ' ' g Format Specifier de-DE Culture 01.10.2008 17:04 ' g Format Specifier en-US Culture 10/1/2008 5:04 PM ' g Format Specifier es-ES Culture 01/10/2008 17:04 ' g Format Specifier fr-FR Culture 01/10/2008 17:04 ' ' G Format Specifier de-DE Culture 01.10.2008 17:04:32 ' G Format Specifier en-US Culture 10/1/2008 5:04:32 PM ' G Format Specifier es-ES Culture 01/10/2008 17:04:32 ' G Format Specifier fr-FR Culture 01/10/2008 17:04:32 ' ' m Format Specifier de-DE Culture 01 Oktober ' m Format Specifier en-US Culture October 01 ' m Format Specifier es-ES Culture 01 octubre ' m Format Specifier fr-FR Culture 1 octobre ' ' o Format Specifier de-DE Culture 2008-10-01T17:04:32.0000000 ' o Format Specifier en-US Culture 2008-10-01T17:04:32.0000000 ' o Format Specifier es-ES Culture 2008-10-01T17:04:32.0000000 ' o Format Specifier fr-FR Culture 2008-10-01T17:04:32.0000000 ' ' r Format Specifier de-DE Culture Wed, 01 Oct 2008 17:04:32 GMT ' r Format Specifier en-US Culture Wed, 01 Oct 2008 17:04:32 GMT ' r Format Specifier es-ES Culture Wed, 01 Oct 2008 17:04:32 GMT ' r Format Specifier fr-FR Culture Wed, 01 Oct 2008 17:04:32 GMT ' ' s Format Specifier de-DE Culture 2008-10-01T17:04:32 ' s Format Specifier en-US Culture 2008-10-01T17:04:32 ' s Format Specifier es-ES Culture 2008-10-01T17:04:32 ' s Format Specifier fr-FR Culture 2008-10-01T17:04:32 ' ' t Format Specifier de-DE Culture 17:04 ' t Format Specifier en-US Culture 5:04 PM ' t Format Specifier es-ES Culture 17:04 ' t Format Specifier fr-FR Culture 17:04 ' ' T Format Specifier de-DE Culture 17:04:32 ' T Format Specifier en-US Culture 5:04:32 PM ' T Format Specifier es-ES Culture 17:04:32 ' T Format Specifier fr-FR Culture 17:04:32 ' ' u Format Specifier de-DE Culture 2008-10-01 17:04:32Z ' u Format Specifier en-US Culture 2008-10-01 17:04:32Z ' u Format Specifier es-ES Culture 2008-10-01 17:04:32Z ' u Format Specifier fr-FR Culture 2008-10-01 17:04:32Z ' ' U Format Specifier de-DE Culture Donnerstag, 2. Oktober 2008 00:04:32 ' U Format Specifier en-US Culture Thursday, October 02, 2008 12:04:32 AM ' U Format Specifier es-ES Culture jueves, 02 de octubre de 2008 0:04:32 ' U Format Specifier fr-FR Culture jeudi 2 octobre 2008 00:04:32 ' ' Y Format Specifier de-DE Culture Oktober 2008 ' Y Format Specifier en-US Culture October, 2008 ' Y Format Specifier es-ES Culture octubre de 2008 ' Y Format Specifier fr-FR Culture octobre 2008
The following example demonstrates different ways of formatting a DateTime value using the invariant DateTimeFormatInfo.
Option Explicit On Option Strict On Imports System.Globalization Public Class Example Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock) Dim dt As DateTime = DateTime.Now Dim myformat() As String = {"d", "D", _ "f", "F", _ "g", "G", _ "m", _ "r", _ "s", _ "t", "T", _ "u", "U", _ "y", _ "dddd, MMMM dd yyyy", _ "ddd, MMM d ""'""yy", _ "dddd, MMMM dd", _ "M/yy", _ "dd-MM-yy"} Dim mydate As String Dim i As Integer For i = 0 To myformat.Length - 1 mydate = dt.ToString(myformat(i), DateTimeFormatInfo.InvariantInfo) outputBlock.Text += String.Format(String.Concat(myformat(i), " :", mydate)) & vbCrLf Next i ' Output. ' ' d :08/17/2000 ' D :Thursday, August 17, 2000 ' f :Thursday, August 17, 2000 16:32 ' F :Thursday, August 17, 2000 16:32:32 ' g :08/17/2000 16:32 ' G :08/17/2000 16:32:32 ' m :August 17 ' r :Thu, 17 Aug 2000 23:32:32 GMT ' s :2000-08-17T16:32:32 ' t :16:32 ' T :16:32:32 ' u :2000-08-17 23:32:32Z ' U :Thursday, August 17, 2000 23:32:32 ' y :August, 2000 ' dddd, MMMM dd yyyy :Thursday, August 17 2000 ' ddd, MMM d "'"yy :Thu, Aug 17 '00 ' dddd, MMMM dd :Thursday, August 17 ' M/yy :8/00 ' dd-MM-yy :17-08-00 End Sub 'Main End Class 'MainClass