Share via

  • Article

DateTime.TryParseExact Method (String, array<String[], IFormatProvider, DateTimeStyles, DateTime%)

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Converts the specified string representation of a date and time to its DateTime equivalent using the specified array of formats, culture-specific format information, and style. The format of the string representation must match at least one of the specified formats exactly. The method returns a value that indicates whether the conversion succeeded.

Namespace:  System
Assembly:  mscorlib (in mscorlib.dll)

Syntax

'Declaration
Public Shared Function TryParseExact ( _
    s As String, _
    formats As String(), _
    provider As IFormatProvider, _
    style As DateTimeStyles, _
    <OutAttribute> ByRef result As DateTime _
) As Boolean

public static bool TryParseExact(
    string s,
    string[] formats,
    IFormatProvider provider,
    DateTimeStyles style,
    out DateTime result
)

Parameters

  • s
    Type: System.String
    A string that contains one or more dates and times to convert.
  • formats
    Type: array<System.String[]
    An array of allowable formats for the s parameter.
  • result
    Type: System.DateTime%
    When this method returns, contains the DateTime value that is equivalent to the date and time contained in s, if the conversion succeeded, or DateTime.MinValue if the conversion failed. The conversion fails if s or formats is nulla null reference (Nothing in Visual Basic), s or an element of formats is an empty string, or the format of s is not exactly as specified by at least one of the format patterns in formats. This parameter is passed uninitialized.

Return Value

Type: System.Boolean
true if the s parameter was converted successfully; otherwise, false.

Exceptions

Exception Condition
ArgumentException

styles is not a valid DateTimeStyles value.

-or-

styles contains an invalid combination of DateTimeStyles values (for example, both AssumeLocal and AssumeUniversal).

Remarks

The DateTime.TryParseExact(String, array<String[], IFormatProvider, DateTimeStyles, DateTime%) method parses the string representation of a date that matches any one of the patterns assigned to the formats parameter. It is like the DateTime.ParseExact(String, array<String[], IFormatProvider, DateTimeStyles) method, except the TryParseExact method does not throw an exception if the conversion fails.

The s parameter contains the date and time to parse. If the s parameter contains only a time and no date, the current date is used unless the style parameter includes the DateTimeStyles.NoCurrentDateDefault flag, in which case the default date (DateTime.Date.MinValue) is used. If the s parameter contains only a date and no time, midnight (00:00:00) is used. The style parameter also determines whether the s parameter can contain leading, inner, or trailing white space characters other than those permitted by one of the format strings in formats.

If s contains no time zone information, the Kind property of the returned DateTime object is DateTimeKind.Unspecified. This behavior can be changed by using the DateTimeStyles.AssumeLocal flag, which returns a DateTime value whose Kind property is DateTimeKind.Local, or by using the DateTimeStyles.AssumeUniversal and DateTimeStyles.AdjustToUniversal flags, which returns a DateTime value whose Kind property is DateTimeKind.Utc. If s contains time zone information, the time is converted to local time, if necessary, and the Kind property of the returned DateTime object is set to DateTimeKind.Local. This behavior can be changed by using the DateTimeStyles.RoundtripKind flag to not convert Coordinated Universal Time (UTC) to a local time and set the Kind property to DateTimeKind.Utc.

The formats parameter contains an array of patterns, one of which s must match exactly if the parse operation is to succeed. The patterns in the formats parameter consist of one or more custom format specifiers from the Custom Date and Time Format Strings table, or a single standard format specifier, which identifies a predefined pattern, from the Standard Date and Time Format Strings table.

If you do not use date or time separators in a custom format pattern, use the invariant culture for the provider parameter and the widest form of each custom format specifier. For example, if you want to specify hours in the pattern, specify the wider form, "HH", instead of the narrower form, "H".

The particular date and time symbols and strings (such as the names of the days of the week in a particular language) used in s are defined by the provider parameter, as is the precise format of s if format is a standard format specifier string. The provider parameter can be any of the following:

If provider is nulla null reference (Nothing in Visual Basic), the CultureInfo object that corresponds to the current culture is used.

The styles parameter includes one or more members of the DateTimeStyles enumeration that determine whether and where white space not defined by format can appear in s and that control the precise behavior of the parse operation. The following table describes how each member of the DateTimeStyles enumeration affects the operation of the TryParseExact(String, array<String[], IFormatProvider, DateTimeStyles, DateTime%) method.

DateTimeStyles member

Description

AdjustToUniversal

Parses s and, if necessary, converts it to UTC. If s includes a time zone offset, or if s contains no time zone information but styles includes the DateTimeStyles.AssumeLocal flag, the method parses the string, calls ToUniversalTime to convert the returned DateTime value to UTC, and sets the Kind property to DateTimeKind.Utc. If s indicates that it represents UTC, or if s does not contain time zone information but styles includes the DateTimeStyles.AssumeUniversal flag, the method parses the string, performs no time zone conversion on the returned DateTime value, and sets the Kind property to DateTimeKind.Utc. In all other cases, the flag has no effect.

AllowInnerWhite

Specifies that white space not defined by format can appear between any individual date or time element.

AllowLeadingWhite

Specifies that white space not defined by format can appear at the beginning of s.

AllowTrailingWhite

Specifies that white space not defined by format can appear at the end of s.

AllowWhiteSpaces

Specifies that s may contain leading, inner, and trailing white spaces not defined by format.

AssumeLocal

Specifies that if s lacks any time zone information, it is assumed to represent a local time. Unless the DateTimeStyles.AdjustToUniversal flag is present, the Kind property of the returned DateTime value is set to DateTimeKind.Local.

AssumeUniversal

Specifies that if s lacks any time zone information, it is assumed to represent UTC. Unless the DateTimeStyles.AdjustToUniversal flag is present, the method converts the returned DateTime value from UTC to local time and sets its Kind property to DateTimeKind.Local.

NoCurrentDateDefault

If s contains time without date information, the date of the return value is set to DateTime.MinValue.Date.

None

The s parameter is parsed using default values. No white space other than that present in format is allowed. If s lacks a date component, the date of the returned DateTime value is set to 1/1/0001. If s contains no time zone information, the Kind property of the returned DateTime object is set to DateTimeKind.Unspecified. If time zone information is present in s, the time is converted to local time and the Kind property of the returned DateTime object is set to DateTimeKind.Local.

RoundtripKind

For strings that contain time zone information, tries to prevent the conversion to a DateTime value with its Kind property set to DateTimeKind.Local. This flag primarily prevents the conversion of UTC times to local times.

Examples

The following example uses the DateTime.TryParseExact(String, String, IFormatProvider, DateTimeStyles, DateTime%) method to ensure that a string in a number of possible formats can be successfully parsed .

Dim formats() As String = {"M/d/yyyy h:mm:ss tt", "M/d/yyyy h:mm tt", _
                           "MM/dd/yyyy hh:mm:ss", "M/d/yyyy h:mm:ss", _
                           "M/d/yyyy hh:mm tt", "M/d/yyyy hh tt", _
                           "M/d/yyyy h:mm", "M/d/yyyy h:mm", _
                           "MM/dd/yyyy hh:mm", "M/dd/yyyy hh:mm"}
Dim dateStrings() As String = {"5/1/2009 6:32 PM", "05/01/2009 6:32:05 PM", _
                               "5/1/2009 6:32:00", "05/01/2009 06:32", _
                               "05/01/2009 06:32:00 PM", "05/01/2009 06:32:00"}

Dim dateValue As DateTime

For Each dateString As String In dateStrings
   If Date.TryParseExact(dateString, formats, _
                         New CultureInfo("en-US"), _
                         DateTimeStyles.None, _
                         dateValue) Then
      outputBlock.Text += String.Format("Converted '{0}' to {1}.", dateString, dateValue) & vbCrLf
   Else
      outputBlock.Text += String.Format("Unable to convert '{0}' to a date.", dateString) & vbCrLf
   End If
Next
' The example displays the following output:
'       Converted '5/1/2009 6:32 PM' to 5/1/2009 6:32:00 PM.
'       Converted '05/01/2009 6:32:05 PM' to 5/1/2009 6:32:05 PM.
'       Converted '5/1/2009 6:32:00' to 5/1/2009 6:32:00 AM.
'       Converted '05/01/2009 06:32' to 5/1/2009 6:32:00 AM.
'       Converted '05/01/2009 06:32:00 PM' to 5/1/2009 6:32:00 PM.
'       Converted '05/01/2009 06:32:00' to 5/1/2009 6:32:00 AM.

string[] formats = {"M/d/yyyy h:mm:ss tt", "M/d/yyyy h:mm tt", 
                   "MM/dd/yyyy hh:mm:ss", "M/d/yyyy h:mm:ss", 
                   "M/d/yyyy hh:mm tt", "M/d/yyyy hh tt", 
                   "M/d/yyyy h:mm", "M/d/yyyy h:mm", 
                   "MM/dd/yyyy hh:mm", "M/dd/yyyy hh:mm"};
string[] dateStrings = {"5/1/2009 6:32 PM", "05/01/2009 6:32:05 PM", 
                        "5/1/2009 6:32:00", "05/01/2009 06:32", 
                        "05/01/2009 06:32:00 PM", "05/01/2009 06:32:00"};
DateTime dateValue;

foreach (string dateString in dateStrings)
{
   if (DateTime.TryParseExact(dateString, formats,
                              new CultureInfo("en-US"),
                              DateTimeStyles.None,
                              out dateValue))
      outputBlock.Text += String.Format("Converted '{0}' to {1}.\n", dateString, dateValue);
   else
      outputBlock.Text += String.Format("Unable to convert '{0}' to a date.\n", dateString);
}
// The example displays the following output:
//       Converted '5/1/2009 6:32 PM' to 5/1/2009 6:32:00 PM.
//       Converted '05/01/2009 6:32:05 PM' to 5/1/2009 6:32:05 PM.
//       Converted '5/1/2009 6:32:00' to 5/1/2009 6:32:00 AM.
//       Converted '05/01/2009 06:32' to 5/1/2009 6:32:00 AM.
//       Converted '05/01/2009 06:32:00 PM' to 5/1/2009 6:32:00 PM.
//       Converted '05/01/2009 06:32:00' to 5/1/2009 6:32:00 AM.

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.