diff --git a/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse2.cs b/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse2.cs index a09548c48a44c..1be2590f2c71e 100644 --- a/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse2.cs +++ b/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse2.cs @@ -11,10 +11,7 @@ public static void Main() foreach (string dateString in dateStrings) { DateTime convertedDate = DateTime.Parse(dateString); - Console.WriteLine("Converted {0} to {1} time {2}", - dateString, - convertedDate.Kind.ToString(), - convertedDate); + Console.WriteLine($"Converted {dateString} to {convertedDate.Kind} time {convertedDate}"); } } } diff --git a/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse5.cs b/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse5.cs index eb2c50fbf71d4..92c4779d1c6bb 100644 --- a/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse5.cs +++ b/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse5.cs @@ -17,12 +17,11 @@ public static void Main() Console.WriteLine(formattedDate); DateTime roundtripDate = DateTime.Parse(formattedDate, null, DateTimeStyles.RoundtripKind); - Console.WriteLine(" With RoundtripKind flag: {0} {1} time.", - roundtripDate, roundtripDate.Kind); + Console.WriteLine($" With RoundtripKind flag: {roundtripDate} {roundtripDate.Kind} time."); + DateTime noRoundtripDate = DateTime.Parse(formattedDate, null, DateTimeStyles.None); - Console.WriteLine(" Without RoundtripKind flag: {0} {1} time.", - noRoundtripDate, noRoundtripDate.Kind); + Console.WriteLine($" Without RoundtripKind flag: {noRoundtripDate} {noRoundtripDate.Kind} time."); } // The example displays the following output: // 2008-09-15T09:30:41.7752486-07:00 diff --git a/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse6.cs b/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse6.cs new file mode 100644 index 0000000000000..2f0711dbb77c0 --- /dev/null +++ b/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse6.cs @@ -0,0 +1,38 @@ +using System; + +public class Example +{ + public static void Main() + { + (string dateAsString, string description)[] dateInfo = { ("08/18/2018 07:22:16", "String with a date and time component"), + ("08/18/2018", "String with a date component only"), + ("8/2018", "String with a month and year component only"), + ("8/18", "String with a month and day component only"), + ("07:22:16", "String with a time component only"), + ("7 PM", "String with an hour and AM/PM designator only"), + ("2018-08-18T07:22:16.0000000Z", "UTC string that conforms to ISO 8601"), + ("2018-08-18T07:22:16.0000000-07:00", "Non-UTC string that conforms to ISO 8601"), + ("Sat, 18 Aug 2018 07:22:16 GMT", "String that conforms to RFC 1123"), + ("08/18/2018 07:22:16 -5:00", "String with date, time, and time zone information" ) }; + + Console.WriteLine($"Today is {DateTime.Now:d}\n"); + + foreach (var item in dateInfo) { + Console.WriteLine($"{item.description + ":",-52} '{item.dateAsString}' --> {DateTime.Parse(item.dateAsString)}"); + } + } +} +// The example displays output like the following: +// Today is 2/22/2018 +// +// String with a date and time component: '08/18/2018 07:22:16' --> 8/18/2018 7:22:16 AM +// String with a date component only: '08/18/2018' --> 8/18/2018 12:00:00 AM +// String with a month and year component only: '8/2018' --> 8/1/2018 12:00:00 AM +// String with a month and day component only: '8/18' --> 8/18/2018 12:00:00 AM +// String with a time component only: '07:22:16' --> 2/22/2018 7:22:16 AM +// String with an hour and AM/PM designator only: '7 PM' --> 2/22/2018 7:00:00 PM +// UTC string that conforms to ISO 8601: '2018-08-18T07:22:16.0000000Z' --> 8/18/2018 12:22:16 AM +// Non-UTC string that conforms to ISO 8601: '2018-08-18T07:22:16.0000000-07:00' --> 8/18/2018 7:22:16 AM +// String that conforms to RFC 1123: 'Sat, 18 Aug 2018 07:22:16 GMT' --> 8/18/2018 12:22:16 AM +// String with date, time, and time zone information: '08/18/2018 07:22:16 -5:00' --> 8/18/2018 5:22:16 AM + diff --git a/samples/snippets/csharp/downloads/api/System/DateTime.Parse.zip b/samples/snippets/csharp/downloads/api/System/DateTime.Parse.zip new file mode 100644 index 0000000000000..c9d60f6f3093e Binary files /dev/null and b/samples/snippets/csharp/downloads/api/System/DateTime.Parse.zip differ diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse2.vb b/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse2.vb index b2dddbd3ade57..709ca366c209f 100644 --- a/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse2.vb +++ b/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse2.vb @@ -4,16 +4,13 @@ Option Strict On ' Module Example Public Sub Main() - Dim dateStrings() As String = {"2008-05-01T07:34:42-5:00", _ - "2008-05-01 7:34:42Z", _ + Dim dateStrings() As String = {"2008-05-01T07:34:42-5:00", + "2008-05-01 7:34:42Z", "Thu, 01 May 2008 07:34:42 GMT"} - For Each dateString As String In dateStrings - Dim convertedDate As Date = Date.Parse(dateString) - Console.WriteLine("Converted {0} to {1} time {2}", _ - dateString, _ - convertedDate.Kind.ToString(), _ - convertedDate) + For Each dateStr In dateStrings + Dim convertedDate As Date = Date.Parse(dateStr) + Console.WriteLine($"Converted {dateStr} to {convertedDate.Kind} time {convertedDate}") Next End Sub End Module diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse3.vb b/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse3.vb index 5029d4e44849c..9c9ee3ee2525d 100644 --- a/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse3.vb +++ b/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse3.vb @@ -15,7 +15,7 @@ Module ParseDate "10.01.2009 19:34", _ "10-1-2009 19:34" } ' Parse dates using each culture. - For Each culture As CultureInfo In cultures + For Each culture In cultures Dim dateValue As Date Console.WriteLine("Attempted conversions using {0} culture.", culture.Name) For Each dateString As String In dateStrings diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse5.vb b/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse5.vb index 30ba331026a56..f100906c05721 100644 --- a/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse5.vb +++ b/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse5.vb @@ -1,45 +1,38 @@ -' Visual Basic .NET Document -Option Strict On Imports System.Globalization - -Module modMain +Public Module Class1 Public Sub Main() ' - Dim formattedDates() As String = { "2008-09-15T09:30:41.7752486-07:00", _ - "2008-09-15T09:30:41.7752486Z", _ - "2008-09-15T09:30:41.7752486", _ - "2008-09-15T09:30:41.7752486-04:00", _ - "Mon, 15 Sep 2008 09:30:41 GMT" } - For Each formattedDate As String In formattedDates - Console.WriteLine(formattedDate) - Dim roundtripDate As Date = Date.Parse(formattedDate, Nothing, _ - DateTimeStyles.RoundtripKind) - Console.WriteLine(" With RoundtripKind flag: {0} {1} time.", _ - roundtripDate, roundtripDate.Kind) - Dim noRoundtripDate As Date = Date.Parse(formattedDate, Nothing, _ - DateTimeStyles.None) - Console.WriteLine(" Without RoundtripKind flag: {0} {1} time.", _ - noRoundtripDate, noRoundtripDate.Kind) - Next + Dim formattedDates() = { "2008-09-15T09:30:41.7752486-07:00", + "2008-09-15T09:30:41.7752486Z", + "2008-09-15T09:30:41.7752486", + "2008-09-15T09:30:41.7752486-04:00", + "Mon, 15 Sep 2008 09:30:41 GMT" } + For Each formattedDate In formattedDates + Console.WriteLine(formattedDate) + Dim roundtripDate = DateTime.Parse(formattedDate, Nothing, + DateTimeStyles.RoundtripKind) + Console.WriteLine($" With RoundtripKind flag: {roundtripDate} {roundtripDate.Kind} time.") + Dim noRoundtripDate = DateTime.Parse(formattedDate, Nothing, DateTimeStyles.None) + Console.WriteLine($" Without RoundtripKind flag: {noRoundtripDate} {noRoundtripDate.Kind} time.") + Next ' The example displays the following output: ' 2008-09-15T09:30:41.7752486-07:00 - ' With RounndtripKind flag: 9/15/2008 9:30:41 AM Local time. + ' With RoundtripKind flag: 9/15/2008 9:30:41 AM Local time. ' Without RoundtripKind flag: 9/15/2008 9:30:41 AM Local time. ' 2008-09-15T09:30:41.7752486Z - ' With RounndtripKind flag: 9/15/2008 9:30:41 AM Utc time. + ' With RoundtripKind flag: 9/15/2008 9:30:41 AM Utc time. ' Without RoundtripKind flag: 9/15/2008 2:30:41 AM Local time. ' 2008-09-15T09:30:41.7752486 - ' With RounndtripKind flag: 9/15/2008 9:30:41 AM Unspecified time. + ' With RoundtripKind flag: 9/15/2008 9:30:41 AM Unspecified time. ' Without RoundtripKind flag: 9/15/2008 9:30:41 AM Unspecified time. ' 2008-09-15T09:30:41.7752486-04:00 - ' With RounndtripKind flag: 9/15/2008 6:30:41 AM Local time. + ' With RoundtripKind flag: 9/15/2008 6:30:41 AM Local time. ' Without RoundtripKind flag: 9/15/2008 6:30:41 AM Local time. ' Mon, 15 Sep 2008 09:30:41 GMT - ' With RounndtripKind flag: 9/15/2008 9:30:41 AM Utc time. + ' With RoundtripKind flag: 9/15/2008 9:30:41 AM Utc time. ' Without RoundtripKind flag: 9/15/2008 2:30:41 AM Local time. ' End Sub End Module - diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse6.vb b/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse6.vb new file mode 100644 index 0000000000000..5cebde44082f2 --- /dev/null +++ b/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse6.vb @@ -0,0 +1,36 @@ + +Public Module Strings + Public Sub Main() + Dim dateInfo() As (dateAsString As String, description As String) = + { ("08/18/2018 07:22:16", "String with a date and time component"), + ("08/18/2018", "String with a date component only"), + ("8/2018", "String with a month and year component only"), + ("8/18", "String with a month and day component only"), + ("07:22:16", "String with a time component only"), + ("7 PM", "String with an hour and AM/PM designator only"), + ("2018-08-18T07:22:16.0000000Z", "UTC string that conforms to ISO 8601"), + ("2018-08-18T07:22:16.0000000-07:00", "Non-UTC string that conforms to ISO 8601"), + ("Sat, 18 Aug 2018 07:22:16 GMT", "String that conforms to RFC 1123"), + ("08/18/2018 07:22:16 -5:00", "String with date, time, and time zone information" ) } + + Console.WriteLine($"Today is {Date.Now:d}{vbCrLf}") + + For Each item in dateInfo + Console.WriteLine($"{item.description + ":",-52} '{item.dateAsString}' --> {DateTime.Parse(item.dateAsString)}") + Next + End Sub +End Module +' The example displays output like the following: +' Today is 2/22/2018 +' +' String with a date and time component: '08/18/2018 07:22:16' --> 8/18/2018 7:22:16 AM +' String with a date component only: '08/18/2018' --> 8/18/2018 12:00:00 AM +' String with a month and year component only: '8/2018' --> 8/1/2018 12:00:00 AM +' String with a month and day component only: '8/18' --> 8/18/2018 12:00:00 AM +' String with a time component only: '07:22:16' --> 2/22/2018 7:22:16 AM +' String with an hour and AM/PM designator only: '7 PM' --> 2/22/2018 7:00:00 PM +' UTC string that conforms to ISO 8601: '2018-08-18T07:22:16.0000000Z' --> 8/18/2018 12:22:16 AM +' Non-UTC string that conforms to ISO 8601: '2018-08-18T07:22:16.0000000-07:00' --> 8/18/2018 7:22:16 AM +' String that conforms to RFC 1123: 'Sat, 18 Aug 2018 07:22:16 GMT' --> 8/18/2018 12:22:16 AM +' String with date, time, and time zone information: '08/18/2018 07:22:16 -5:00' --> 8/18/2018 5:22:16 AM + diff --git a/samples/snippets/visualbasic/downloads/api/System/DateTime.Parse.zip b/samples/snippets/visualbasic/downloads/api/System/DateTime.Parse.zip new file mode 100644 index 0000000000000..7bc2ca0f92e1f Binary files /dev/null and b/samples/snippets/visualbasic/downloads/api/System/DateTime.Parse.zip differ diff --git a/xml/System/DateTime.xml b/xml/System/DateTime.xml index 9a2af32955eba..21c8a7c267b33 100644 --- a/xml/System/DateTime.xml +++ b/xml/System/DateTime.xml @@ -4236,130 +4236,79 @@ juillet 2009 ## Remarks In this section: - [Overloaded method syntax](#Syntax) - [Parameters](#Params) - [Return value](#Returns) - [Exceptions](#Exceptions) [Which method do I call?](#Tasks) [The string to parse](#StringToParse) [Parsing and cultural conventions](#Culture) [Parsing and style elements](#Styles) - Examples: - [DateTime.Parse(String)](#Parse1_Example) - [DateTime.Parse(String, IFormatProvider)](#Parse2_Example) - [DateTime.Parse(String, IFormatProvider, DateTimeStyles)](#Parse3_Example) -[Version information](#Versions) - - -## Overloaded method syntax - For additional guidance on choosing an overload, see [Which method do I call?](#Tasks) - - `DateTime.Parse(String s)` - For the conversion, uses the formatting conventions of the current thread culture and interprets the string based on the style flag ([example](#Parse1_Example)). - - `DateTime.Parse(String s, IFormatProvider provider)` - For the conversion, uses the formatting conventions of a specified culture and interprets the string based on the style flag ([example](#Parse2_Example)). - - `DateTime.Parse(String s, IFormatProvider provider, DateTypeStyles styles)` - For the conversion, uses the formatting conventions of a specified culture and interprets the string based on specified style flags ([example](#Parse3_Example)). - - -## Parameters - This is a complete list of parameters for the method. For the parameters used by each overload, see the overload syntax above. - -|Parameter|Type|Description| -|---------------|----------|-----------------| -|`s`||A string that contains the date and time to convert. See [The string to parse](#StringToParse).

Default value: None (parameter is used by all overloads)| -|`provider`||An object that supplies culture-specific formatting information about `s`. See [Parsing and cultural conventions](#Culture).

Default value: | -|`styles`||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 . See [Parsing and style elements](#Styles).

Default value: | - - -## Return value - Type: -An object that is equivalent to the date and time contained in `s`. - - Generally, the method returns a object whose property is . However, the method may also perform time zone conversion and set the value of the property differently, depending on the values of the `s` and `styles` parameters: - -|If|Time zone conversion|Kind property| -|--------|--------------------------|-------------------| -|`s` contains time zone information.|The date and time is converted to the time in the local time zone.|| -|`s` contains time zone information, and `styles` includes the flag.|The date and time is converted to Coordinated Universal Time (UTC).|| -|`s` contains the Z or GMT time zone designator, and `styles` includes the flag.|The date and time are interpreted as UTC.|| - - The following example converts date strings that contain time zone information to the time in the local time zone: - - [!code-csharp[System.DateTime.Parse#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse2.cs#2)] - [!code-vb[System.DateTime.Parse#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse2.vb#2)] - - You can also preserve the value of a date and time's property during a formatting and parsing operation by using the flag. The following example illustrates how the flag affects the parsing operation on values that are converted to strings by using the "o", "r", or "u" format specifier. - - [!code-csharp[System.DateTime.Parse#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse5.cs#5)] - [!code-vb[System.DateTime.Parse#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse5.vb#5)] - - -## Exceptions - -|Exception|Condition|Thrown by| -|---------------|---------------|---------------| -||`s` is `null`.|All overloads| -||`s` does not contain a valid string representation of a date and time.|All overloads| -||`styles` contains an invalid combination of values (for example, it includes both and ).|| - + [The return value and DateTime.Kind](#kind) + -## Which method do I call? +### Which method do I call? |To|Call| |--------|----------| |Parse a date and time string by using the conventions of the current culture.| overload| |Parse a date and time string by using the conventions of a specific culture.| overload (see [Parsing and Cultural Conventions](#Culture))| |Parse a date and time string with special style elements (such as white space or no white space).| overload| +|Parse a date and time string that must be in a particular format.| or | |Parse a date and time string and perform a conversion to UTC or local time.| overload| |Parse a date and time string without handling exceptions.| method| |Restore (round-trip) a date and time value created by a formatting operation.|Pass the "o" or "r" standard format string to the method, and call the overload with | |Parse a date and time string in a fixed format across machine (and possibly cultural) boundaries.| or method| -## The string to parse - The method tries to convert the string representation of a date and time value to its equivalent. It tries to parse `s` completely without throwing a exception. +### The string to parse + The method tries to convert the string representation of a date and time value to its equivalent. It tries to parse the input string completely without throwing a exception. > [!IMPORTANT] -> Because the string representation of a date and time must conform to a recognized pattern, you should always use exception handling when calling the method to parse user input. If you don't want to handle exceptions, you can call the method to parse the date and time string; this method returns a value that indicates whether the parse operation succeeded. - +> If the parsing operation fails because of an unrecognized string format, the method throws a , whereas the method returns `false`. Because exception handling can be expensive, you should use when the parsing operation is expected to succeed because the input source is trusted. is preferable when parsing failures are likely, particularly because an input source is not trusted, or you have reasonable default values to substitute for strings that do not parse successfully. + The string to be parsed can take any of the following forms: - A string with a date and a time component. - A string with a date but no time component. If the time component is absent, the method assumes 12:00 midnight. If the date component has a two-digit year, it is converted to a year based on the of the current culture's current calendar or the specified culture's current calendar (if you use an overload with a non-null `provider` argument). -- A string with a time but no date component. The method assumes the current date unless you call the overload and include in the `styles` parameter, in which case the method assumes January 1, 0001. - -- A string that includes time zone information and conforms to ISO 8601. In the following examples, the first string designates Coordinated Universal Time (UTC), and the second string designates the time in a time zone that's seven hours earlier than UTC: +- A string with a date component that includes only the month and the year but no day component. The method assumes the first day of the month. + +- A string with a date component that includes only the month and the day but no year component. The method assumes the current year. + +- A string with a time but no date component. The method assumes the current date unless you call the overload and include in the `styles` argument, in which case the method assumes a date of January 1, 0001. + +- A string with a time component that includes only the hour and an AM/PM designator, with no date component. The method assumes the current date and a time with no minutes and no seconds. You can change this behavior by calling the overload and include in the `styles` argument, in which case the method assumes a date of January 1, 0001. + +- A string that includes time zone information and conforms to ISO 8601. In the following examples, the first string designates Coordinated Universal Time (UTC), and the second designates the time in a time zone that's seven hours earlier than UTC: - 2008-11-01T19:35:00.0000000Z - 2008-11-01T19:35:00.0000000-07:00 + "2008-11-01T19:35:00.0000000Z" + "2008-11-01T19:35:00.0000000-07:00" - A string that includes the GMT designator and conforms to the RFC 1123 time format; for example: - Sat, 01 Nov 2008 19:35:00 GMT + "Sat, 01 Nov 2008 19:35:00 GMT" - A string that includes the date and time along with time zone offset information; for example: - 03/01/2009 05:42:00 -5:00 + "03/01/2009 05:42:00 -5:00" + +The following example parses strings in each of these formats by using the formatting conventions of the current culture, which in this case is the en-US culture: + +[!code-csharp-interactive[Default parsing](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse6.cs)] +[!code-vb[Default parsing](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse6.vb)] - If `s` is the string representation of a leap day in a leap year in the calendar used by the parsing method (see [Parsing and cultural conventions](#Culture)), the method parses `s` successfully. If `s` is the string representation of a leap day in a non-leap year, the method throws a exception. + If the input string represents a leap day in a leap year in the calendar used by the parsing method (see [Parsing and cultural conventions](#Culture)), the method parses the string successfully. If the input string represents a leap day in a non-leap year, the method throws a . - Because the method tries to parse the string representation of a date and time by using the formatting rules of the current or specified culture, trying to parse a string across different cultures can fail. To parse a specific date and time format across different locales, use one of the overloads of the method and provide a format specifier. + Because the method tries to parse the string representation of a date and time by using the formatting rules of the current or a specified culture, trying to parse a string across different cultures can fail. To parse a specific date and time format across different locales, use one of the overloads of the method and provide a format specifier. -## Parsing and cultural conventions - All overloads of the method are culture-sensitive unless the string to be parsed conforms to the ISO 8601 pattern. The parsing operation usesthe formatting information in a object that is derived as follows: +### Parsing and cultural conventions + All overloads of the method are culture-sensitive unless the string to be parsed (which is represented by `s` in the following table) conforms to the ISO 8601 pattern. The parsing operation uses the formatting information in a object that is derived as follows: |If you call|And `provider` is|Formatting information is derived from| |-----------------|-----------------------|--------------------------------------------| ||-|The current thread culture ( property)| -| or | object|The specified object| +| or |a object|The specified object| | or |`null`|The current thread culture ( property)| -| or | object|The property| +| or |a object|The property| | or |Custom implementation|The method| When formatting information is derived from a object, the property defines the calendar used in the parsing operation. @@ -4378,8 +4327,8 @@ An object that is equivalent to the date and time contained in `s`. > For more information see the "Dynamic culture data" section in the topic and the "Persisting DateTime values" section in the topic. -## Parsing and style elements - All overloads ignore leading, inner, or trailing white-space characters in `s`. The date and time can be bracketed with a pair of leading and trailing NUMBER SIGN characters ("#", U+0023), and can be trailed with one or more NULL characters (U+0000). +### Parsing and style elements + All overloads ignore leading, inner, or trailing white-space characters in the input string (which is represented by `s` in the following table). The date and time can be bracketed with a pair of leading and trailing NUMBER SIGN characters ("#", U+0023), and can be trailed with one or more NULL characters (U+0000). In addition, the overload has a `styles` parameter that consists of one or more members of the enumeration. This parameter defines how `s` should be interpreted and how the parse operation should convert `s` to a date and time. The following table describes the effect of each member on the parse operation. @@ -4394,42 +4343,42 @@ An object that is equivalent to the date and time contained in `s`. ||Specifies that if `s` lacks any time zone information, UTC is assumed. Unless the flag is present, the method converts the returned value from UTC to local time and sets its property to .| ||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 value that represents a local time with its property set to . Typically, such a string is created by calling the method and by using the "o", "r", or "u" standard format specifier.| + + +### The return value and DateTime.Kind + +The `DateTime.Parse` overloads return a value whose property includes time zone information. It can indicate that the time is: + +- Coordinated Universal Time (). +- The time in the local time zone (). +- The time in an unknown time zone (xref:System.DateTimeKind.Unspecified?displayProperty=fullName>). + + Generally, the method returns a object whose property is . However, the method may also perform time zone conversion and set the value of the property differently, depending on the values of the `s` and `styles` parameters: - -## DateTime.Parse(String) example - The following example parses the string representation of several date and time values by using default provider and style values: the formatting conventions of the en-US culture, which is the current thread culture of the computer used to produce the example output, and the style flag. It handles the exception that is thrown when the method tries to parse the string representation of a date and time by using some other culture's formatting conventions. It also shows how to successfully parse a date and time value that does not use the formatting conventions of the current thread culture. - - [!code-csharp[System.DateTime.Parse#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse1.cs#1)] - [!code-vb[System.DateTime.Parse#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse1.vb#1)] - - -## DateTime.Parse(String, IFormatProvider) example - The following example parses an array of date strings by using the conventions of the en-US, fr-FR, and de-DE cultures. It demonstrates that the string representations of a single date can be interpreted differently across different cultures. - - [!code-csharp[System.DateTime.Parse#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse3.cs#3)] - [!code-vb[System.DateTime.Parse#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse3.vb#3)] - - -## DateTime.Parse(String, IFormatProvider, DateTimeStyles) example - The following example demonstrates the method and displays the value of the property of the resulting values. - - [!code-csharp[System.DateTime.Parse#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse4.cs#4)] - [!code-vb[System.DateTime.Parse#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse4.vb#4)] - - -## Version information - .NET Framework - All overloads are supported in: 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0 +|If|Time zone conversion|Kind property| +|--------|--------------------------|-------------------| +|`s` contains time zone information.|The date and time is converted to the time in the local time zone.|| +|`s` contains time zone information, and `styles` includes the flag.|The date and time is converted to Coordinated Universal Time (UTC).|| +|`s` contains the Z or GMT time zone designator, and `styles` includes the flag.|The date and time are interpreted as UTC.|| - .NET Framework Client Profile - All overloads are supported in: 4, 3.5 SP1 + The following example converts date strings that contain time zone information to the time in the local time zone: - Portable Class Library - All overloads are supported + [!code-csharp-interactive[System.DateTime.Parse#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse2.cs#2)] + [!code-vb[System.DateTime.Parse#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse2.vb#2)] + + You can also preserve the value of a date and time's property during a formatting and parsing operation by using the flag. The following example illustrates how the flag affects the parsing operation on values that are converted to strings by using the "o", "r", or "u" format specifier. - .NET for Windows Store apps - All overloads are supported in: Windows 8 + [!code-csharp-interactive[System.DateTime.Parse#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse5.cs#5)] + [!code-vb[System.DateTime.Parse#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse5.vb#5)] +### Examples + +Numerous examples that call the `DateTime.Parse` method are interspersed throughout the [Remarks](#remarks) section of this article and in the documentation for the individual `DateTime.Parse` overloads. + +[!INCLUDE[interactive-note](~/includes/csharp-interactive-note.md)] + +You can also download a complete set of `DateTime.Parse` examples, which are included in a [.NET Core 2.0 project for C#](~/samples/snippets/csharp/downloads/api/System/DateTime.Parse.zip) and a [.NET Core 2.0 project for Visual Basic](~/samples/snippets/visualbasic/downloads/api/System.DateTime.Parse.zip), from the [dotnet/docs GitHub repository](https://github.com/dotnet/docs). + ]]> @@ -4465,17 +4414,33 @@ An object that is equivalent to the date and time contained in `s`. - A string that contains a date and time to convert. - Converts the string representation of a date and time to its equivalent. + A string that contains a date and time to convert. See [The string to parse](#StringToParse) for more information. + Converts the string representation of a date and time to its equivalent by using the conventions of the current thread culture. An object that is equivalent to the date and time contained in . [!NOTE] -> For examples and comprehensive usage information about this and other overloads of the `Parse` method, see the overload summary. +If `s` contains time zone information, this method returns a value whose property is and converts the date and time in `s` to local time. Otherwise, it performs no time zone conversion and returns a value whose property is . + +This overload attempts to parse `s` by using the formatting conventions of the current culture. The current culture is indicated by the property. To parse a string using the formatting conventions of a specific culture, call the or the overloads. + +This overload attempts to parse `s` by using style. + +## Example + +The following example parses the string representation of several date and time values by: + +- Using the default format provider, which provides the formatting conventions of hte current thread culture of the computer used to produce the example output. The output from this example reflects the formatting conventions of the en-US culture. + +- Using the default style value, which is . + +It handles the exception that is thrown when the method tries to parse the string representation of a date and time by using some other culture's formatting conventions. It also shows how to successfully parse a date and time value that does not use the formatting conventions of the current thread culture. + [!code-csharp-interactive[System.DateTime.Parse#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse1.cs#1)] + [!code-vb[System.DateTime.Parse#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse1.vb#1)] + ]]> @@ -4517,8 +4482,8 @@ An object that is equivalent to the date and time contained in `s`. - A string that contains a date and time to convert. - An object that supplies culture-specific format information about s. + A string that contains a date and time to convert. See [The string to parse](#StringToParse) for more information. + An object that supplies culture-specific format information about s. See [Parsing and cultural conventions](#Culture) Converts the string representation of a date and time to its equivalent by using culture-specific format information. An object that is equivalent to the date and time contained in as specified by . @@ -4526,8 +4491,16 @@ An object that is equivalent to the date and time contained in `s`. ## Remarks -> [!NOTE] -> For examples and comprehensive usage information about this and other overloads of the `Parse` method, see the overload summary. +If `s` contains time zone information, this method returns a value whose property is and converts the date and time in `s` to local time. Otherwise, it performs no time zone conversion and returns a value whose property is . + +This overload attempts to parse `s` by using the style. + +## Example + +The following example parses an array of date strings by using the conventions of the en-US, fr-FR, and de-DE cultures. It demonstrates that the string representations of a single date can be interpreted differently across different cultures. + +[!code-csharp-interactive[System.DateTime.Parse#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse3.cs#3)] +[!code-vb[System.DateTime.Parse#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse3.vb#3)] ]]> @@ -4571,18 +4544,31 @@ An object that is equivalent to the date and time contained in `s`. - A string that contains a date and time to convert. - An object that supplies culture-specific formatting information about s. + A string that contains a date and time to convert. See [The string to parse](#StringToParse) for more information. + An object that supplies culture-specific formatting information about s. See [Parsing and cultural conventions](#Culture) 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 . - Converts the string representation of a date and time to its equivalent by using culture-specific format information and formatting style. + Converts the string representation of a date and time to its equivalent by using culture-specific format information and a formatting style. An object that is equivalent to the date and time contained in , as specified by and . property of the returned value as follows: + +|If |Time zone conversion|Kind property| +|-----|-----|-----| +|`s` contains no time zone information.|None.|| +|`s` contains time zone information.|To the time in the local time zone|| +|`s` contains time zone information, and `styles includes the flag.|To Coordinated Univeral Time (UTC)|| +|`s` contains the Z or GMT time zone designator, and `styles` includes the .|None.|| + +## Example + +The following example demonstrates the method and displays the value of the property of the resulting values. -> [!NOTE] -> For examples and comprehensive usage information about this and other overloads of the `Parse` method, see the overload summary. +[!code-csharp-interactive[System.DateTime.Parse#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTime.Parse/cs/Parse4.cs#4)] +[!code-vb[System.DateTime.Parse#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTime.Parse/vb/Parse4.vb#4)] ]]>