DateTime::Parse Method (String, IFormatProvider, DateTimeStyles)
Updated: July 2008
Converts the specified string representation of a date and time to its DateTime equivalent using the specified culture-specific format information and formatting style.
Assembly: mscorlib (in mscorlib.dll)
public: static DateTime Parse( String^ s, IFormatProvider^ provider, DateTimeStyles styles )
Parameters
- s
- Type: System::String
A string containing a date and time to convert.
- provider
- Type: System::IFormatProvider
An object that supplies culture-specific formatting information about s.
- styles
- Type: System.Globalization::DateTimeStyles
A bitwise combination of the enumeration values that indicates the style elements that can be present in s for the parse operation to succeed and that defines how to interpret the parsed date in relation to the current time zone or the current date. A typical value to specify is None.
Return Value
Type: System::DateTimeA DateTime equivalent to the date and time contained in s as specified by provider and styles.
| Exception | Condition |
|---|---|
| ArgumentNullException | s is nullptr. |
| FormatException | s does not contain a valid string representation of a date and time. |
| ArgumentException | styles contains an invalid combination of DateTimeStyles values. For example, both AssumeLocal and AssumeUniversal. |
This method parses a string with two elements that can appear in any order and are delimited by white space. These two elements are shown in the following table.
Date and time element | Example (en-US culture) |
|---|---|
<Date> | "2/10/2009" |
<Time> | "1:02:03 PM" |
Either <Date> or <Time> but not both elements can be absent from s. In addition, s can contain time zone information. If <Time> is missing, its default value is 12:00:00 AM. If <Date> is missing, its default value is the current day. However, if <Date> is missing and styles includes the NoCurrentDateDefault value, its date is assumed to be January 1, 0001. Each element can also be enclosed by leading or trailing white space and can even include inner white space (such as "6: 00: 00"). A time zone specifier (such as Z or GMT to indicate Coordinated Universal Time (UTC)) can also be present. In addition, s can include a time zone offset (such as "2008-10-1T6:00:32-8:00"). In this case, the format of s must conform to the ISO 8601 standard.
The format of s is defined by the provider parameter, which can be any of the following:
A CultureInfo object that represents the culture whose formatting is used in the input parameter. The DateTimeFormatInfo object returned by the CultureInfo::DateTimeFormat property defines the formatting used in s.
A DateTimeFormatInfo object that defines the formatting used in s.
A custom IFormatProvider implementation. Its IFormatProvider::GetFormat method returns a DateTimeFormatInfo object that defines the formatting used in s.
Specific valid formats for date and time elements are defined by the members of the string array that is returned by the DateTimeFormatInfo::GetAllDateTimePatterns() method. If provider is nullptr, the CultureInfo object for the current culture is used.
The styles parameter consists of one or more members of the DateTimeStyles enumeration that define how s is to be interpreted and how the parse operation is to convert s to a date and time. The following table describes the effect of each member on the parse operation.
DateTimeStyles member | Description |
|---|---|
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. | |
Although valid, this value is ignored. Inner white space is permitted in the date and time elements of s. | |
Although valid, this value is ignored. Leading white space is permitted in the date and time elements of s. | |
Although valid, this value is ignored. Trailing white space is permitted in the date and time elements of s. | |
Specifies that s may contain leading, inner, and trailing white spaces. This is the default behavior. It cannot be overridden by supplying a more restrictive DateTimeStyles enumeration value such as DateTimeStyles::None. | |
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. | |
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. | |
Although valid, this value is ignored. | |
For strings that contain time zone information, tries to prevent the conversion of a date and time string to a DateTime value that represents a local time with its Kind property set to DateTimeKind::Local. Typically, such a string is created by calling the DateTime::ToString(String) method using either the "o", "r", or "u" standard format specifiers. |
If s contains no time zone information, the DateTime::Parse(String, IFormatProvider, DateTimeStyles) method returns a DateTime value whose Kind property is DateTimeKind::Unspecified unless a styles flag indicates otherwise. If s includes time zone or time zone offset information, the DateTime::Parse(String, IFormatProvider, DateTimeStyles) method performs any necessary time conversion and returns one of the following:
A DateTime value whose date and time reflect the local time and whose Kind property is DateTimeKind::Local.
Or, if styles includes the AdjustToUniversal flag, a DateTime value whose date and time reflect UTC and whose Kind property is DateTimeKind::Utc.
This behavior can be overridden by using the DateTimeStyles::RoundtripKind flag. The following example illustrates how the DateTimeStyles::RoundtripKind flag affects the parsing operation on DateTime values that are converted to strings using the "o", "r", or "u" format specifier.
Because the DateTime::Parse(String, IFormatProvider, DateTimeStyles) method tries to parse the string representation of a date and time using the formatting rules of the provider parameter, trying to parse a particular string across different cultures can fail. If a specific date and time format will be parsed across different locales, use one of the overloads of the ParseExact method and provide a format specifier.
Parsing Custom Cultures
If you parse a date and time string generated for a custom culture, use the ParseExact method instead of the Parse method to improve the probability that the parse operation will succeed. A custom culture date and time string can be complicated, and therefore difficult to parse. The Parse method attempts to parse a string with several implicit parse patterns, all of which might fail. The ParseExact method, in contrast, requires you to explicitly designate one or more exact parse patterns that are likely to succeed.
For more information about custom cultures, see the System.Globalization::CultureAndRegionInfoBuilder class.
Formatting is influenced by properties of the current DateTimeFormatInfo object, which is supplied by the provider parameter. One reason the Parse method can unexpectedly throw FormatException is if the current DateTimeFormatInfo::DateSeparator and DateTimeFormatInfo::TimeSeparator properties are set to the same value.
Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune
The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Date | History | Reason |
|---|---|---|
July 2008 | Added remarks and an example about the Kind property and the DateTimeStyles::RoundtripKind flag. | Content bug fix. |