DateTime.Parse Method (String, IFormatProvider) (System)

Parse Method (String, IFormatProvid...

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Class Library

DateTime..::.Parse Method (String, IFormatProvider)

Converts the specified string representation of a date and time to its DateTime equivalent using the specified culture-specific format information.

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

Syntax

Visual Basic (Declaration)

Public Shared Function Parse ( _
    s As String, _
    provider As IFormatProvider _
) As DateTime

Visual Basic (Usage)

Dim s As String
Dim provider As IFormatProvider
Dim returnValue As DateTime

returnValue = DateTime.Parse(s, provider)

public static DateTime Parse(
    string s,
    IFormatProvider provider
)

Visual C++

public:
static DateTime Parse(
    String^ s, 
    IFormatProvider^ provider
)

JScript

public static function Parse(
    s : String, 
    provider : IFormatProvider
) : DateTime

Parameters

s: Type: System..::.String
A string containing a date and time to convert.

provider: Type: System..::.IFormatProvider
An object that supplies culture-specific format information about s.

Return Value

Type: System..::.DateTime
A DateTime equivalent to the date and time contained in s as specified by provider.

Exceptions

Exception	Condition
ArgumentNullException	s is nullNothingnullptra null reference (Nothing in Visual Basic).
FormatException	s does not contain a valid string representation of a date and time.

Remarks

The string s is parsed using formatting information in the DateTimeFormatInfo object that is supplied either explicitly or implicitly by the provider parameter. The s parameter must contain the representation of a date and time in one of the formats returned by the DateTimeFormatInfo..::.GetAllDateTimePatterns()()() method of the culture specified by provider.

Important Note:
Because the string representation of a date and time must conform to a recognized pattern, applications should always use exception handling when calling the Parse(String) method to parse user input.

This method attempts to parse s completely and avoid throwing a FormatException. It ignores unrecognized data if possible and fills in missing month, day, and year information with the current date. If s contains only a date and no time, this method assumes 12:00 midnight. If s contains only a time and no date, this method assumes the current date. Any leading, inner, or trailing white space character in s is ignored. 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).

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 s parameter. The DateTimeFormatInfo object returned by the CultureInfo..::.DateTimeFormat property defines the possible formatting that can be used in s.
A DateTimeFormatInfo object that defines the format of the date and time data.
A custom object that implements IFormatProvider and whose IFormatProvider..::.GetFormat method returns a DateTimeFormatInfo object that provides formatting information.

If provider is nullNothingnullptra null reference (Nothing in Visual Basic), the current culture is used.

In most cases, the Parse(String) method returns a DateTime value whose Kind property is DateTimeKind..::.Unspecified. However, if the string to be parsed contains time zone information as defined by ISO 8601 or if it includes the older GMT designator, the Parse(String) method performs any necessary time conversion and returns a DateTime value whose date and time reflects the local time and whose Kind property is DateTimeKind..::.Local.

Because the DateTime..::.Parse(String, IFormatProvider) 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 either fail or return different results. 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 Non-Standard Cultures

If you parse a date and time string using a CultureInfo or DateTimeFormatInfo object which includes customized settings that are different from those of a standard culture, use the ParseExact method instead of the Parse method to improve the probability that the parse operation will succeed. A non-standard date and time string can be complicated and difficult to parse. The Parse method tries to parse a string with several implicit parse patterns, all of which might fail. In contrast, the ParseExact method requires you to explicitly designate one or more exact parse patterns that are likely to succeed.

For more information about custom or non-standard cultures, see the System.Globalization..::.CultureAndRegionInfoBuilder class.

Notes to Callers:

Formatting is influenced by properties of the DateTimeFormatInfo object that 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.

Examples

The following example demonstrates the DateTime..::.Parse(String, IFormatProvider) method. It also illustrates the fact that string representations of a single date can be interpreted differently across different cultures.

Visual Basic

Imports System.Globalization

Module ParseDate
   Public Sub Main()
      ' Define cultures to be used to parse dates.
      Dim cultures() As CultureInfo = {CultureInfo.CreateSpecificCulture("en-US"), _
                                       CultureInfo.CreateSpecificCulture("fr-FR"), _
                                       CultureInfo.CreateSpecificCulture("de-DE")}
      ' Define string representations of a date to be parsed.
      Dim dateStrings() As String = {"01/10/2009 7:34 PM", _
                                     "10.01.2009 19:34", _
                                     "10-1-2009 19:34" }
      ' Parse dates using each culture.
      For Each culture As CultureInfo In cultures
         Dim dateValue As Date
         Console.WriteLine("Attempted conversions using {0} culture.", culture.Name)
         For Each dateString As String In dateStrings
            Try
               dateValue = Date.Parse(dateString, culture)
               Console.WriteLine("   Converted '{0}' to {1}.", _
                                 dateString, dateValue.ToString("f", culture))
            Catch e As FormatException
               Console.WriteLine("   Unable to convert '{0}' for culture {1}.", _
                                 dateString, culture.Name)
            End Try                                                
         Next
         Console.WriteLine()
      Next                                                                                     
   End Sub
End Module
' The example displays the following output to the console:
'       Attempted conversions using en-US culture.
'          Converted '01/10/2009 7:34 PM' to Saturday, January 10, 2009 7:34 PM.
'          Converted '10.01.2009 19:34' to Thursday, October 01, 2009 7:34 PM.
'          Converted '10-1-2009 19:34' to Thursday, October 01, 2009 7:34 PM.
'       
'       Attempted conversions using fr-FR culture.
'          Converted '01/10/2009 7:34 PM' to jeudi 1 octobre 2009 19:34.
'          Converted '10.01.2009 19:34' to samedi 10 janvier 2009 19:34.
'          Converted '10-1-2009 19:34' to samedi 10 janvier 2009 19:34.
'       
'       Attempted conversions using de-DE culture.
'          Converted '01/10/2009 7:34 PM' to Donnerstag, 1. Oktober 2009 19:34.
'          Converted '10.01.2009 19:34' to Samstag, 10. Januar 2009 19:34.
'          Converted '10-1-2009 19:34' to Samstag, 10. Januar 2009 19:34.

using System;
using System.Globalization;

public class ParseDate
{
   public static void Main()
   {
      // Define cultures to be used to parse dates.
      CultureInfo[] cultures = {CultureInfo.CreateSpecificCulture("en-US"), 
                                CultureInfo.CreateSpecificCulture("fr-FR"), 
                                CultureInfo.CreateSpecificCulture("de-DE")};
      // Define string representations of a date to be parsed.
      string[] dateStrings = {"01/10/2009 7:34 PM", 
                              "10.01.2009 19:34", 
                              "10-1-2009 19:34" };
      // Parse dates using each culture.
      foreach (CultureInfo culture in cultures)
      {
         DateTime dateValue;
         Console.WriteLine("Attempted conversions using {0} culture.", 
                           culture.Name);
         foreach (string dateString in dateStrings)
         {
            try {
               dateValue = DateTime.Parse(dateString, culture);
               Console.WriteLine("   Converted '{0}' to {1}.",
                                 dateString, dateValue.ToString("f", culture));
            }
            catch (FormatException) {
               Console.WriteLine("   Unable to convert '{0}' for culture {1}.", 
                                 dateString, culture.Name);
            }
         }
         Console.WriteLine();
      }                                                                                     
   }
}
// The example displays the following output to the console:
//       Attempted conversions using en-US culture.
//          Converted '01/10/2009 7:34 PM' to Saturday, January 10, 2009 7:34 PM.
//          Converted '10.01.2009 19:34' to Thursday, October 01, 2009 7:34 PM.
//          Converted '10-1-2009 19:34' to Thursday, October 01, 2009 7:34 PM.
//       
//       Attempted conversions using fr-FR culture.
//          Converted '01/10/2009 7:34 PM' to jeudi 1 octobre 2009 19:34.
//          Converted '10.01.2009 19:34' to samedi 10 janvier 2009 19:34.
//          Converted '10-1-2009 19:34' to samedi 10 janvier 2009 19:34.
//       
//       Attempted conversions using de-DE culture.
//          Converted '01/10/2009 7:34 PM' to Donnerstag, 1. Oktober 2009 19:34.
//          Converted '10.01.2009 19:34' to Samstag, 10. Januar 2009 19:34.
//          Converted '10-1-2009 19:34' to Samstag, 10. Januar 2009 19:34.

Platforms

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.

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Reference

Other Resources

Parsing Date and Time Strings

Date and Time Format Strings