DateTimeOffset.ParseExact Method

Definition

Converts the specified string representation of a date and time to its DateTimeOffset equivalent. The format of the string representation must match a specified format exactly.

Overloads

ParseExact(String, String[], IFormatProvider, DateTimeStyles)

Converts the specified string representation of a date and time to its DateTimeOffset equivalent using the specified formats, culture-specific format information, and style. The format of the string representation must match one of the specified formats exactly.

ParseExact(String, String, IFormatProvider, DateTimeStyles)

Converts the specified string representation of a date and time to its DateTimeOffset equivalent using the specified format, culture-specific format information, and style. The format of the string representation must match the specified format exactly.

ParseExact(String, String, IFormatProvider)

Converts the specified string representation of a date and time to its DateTimeOffset equivalent using the specified format and culture-specific format information. The format of the string representation must match the specified format exactly.

ParseExact(ReadOnlySpan<Char>, ReadOnlySpan<Char>, IFormatProvider, DateTimeStyles)

Converts a character span that represents a date and time to its DateTimeOffset equivalent using the specified format, culture-specific format information, and style. The format of the date and time representation must match the specified format exactly.

ParseExact(ReadOnlySpan<Char>, String[], IFormatProvider, DateTimeStyles)

Converts a character span that contains the string representation of a date and time to its DateTimeOffset equivalent using the specified formats, culture-specific format information, and style. The format of the date and time representation must match one of the specified formats exactly.

ParseExact(String, String[], IFormatProvider, DateTimeStyles)

Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs

Converts the specified string representation of a date and time to its DateTimeOffset equivalent using the specified formats, culture-specific format information, and style. The format of the string representation must match one of the specified formats exactly.

public static DateTimeOffset ParseExact (string input, string[] formats, IFormatProvider formatProvider, System.Globalization.DateTimeStyles styles);
public static DateTimeOffset ParseExact (string input, string[] formats, IFormatProvider? formatProvider, System.Globalization.DateTimeStyles styles);

Parameters

input
String

A string that contains a date and time to convert.

formats
String[]

An array of format specifiers that define the expected formats of input.

formatProvider
IFormatProvider

An object that supplies culture-specific formatting information about input.

styles
DateTimeStyles

A bitwise combination of enumeration values that indicates the permitted format of input.

Returns

An object that is equivalent to the date and time that is contained in the input parameter, as specified by the formats, formatProvider, and styles parameters.

Exceptions

The offset is greater than 14 hours or less than -14 hours.

-or-

styles includes an unsupported value.

-or-

The styles parameter contains DateTimeStyles values that cannot be used together.

input is null.

input is an empty string ("").

-or-

input does not contain a valid string representation of a date and time.

-or-

No element of formats contains a valid format specifier.

-or-

The hour component and the AM/PM designator in input do not agree.

Examples

The following example defines multiple input formats for the string representation of a date and time and offset value, and then passes the string that is entered by the user to the DateTimeOffset.ParseExact(String, String[], IFormatProvider, DateTimeStyles) method.

TextReader conIn = Console.In;
TextWriter conOut = Console.Out;
int tries = 0;
string input = String.Empty;
string[] formats = new string[] {@"@M/dd/yyyy HH:m zzz", @"MM/dd/yyyy HH:m zzz",
                                 @"M/d/yyyy HH:m zzz", @"MM/d/yyyy HH:m zzz",
                                 @"M/dd/yy HH:m zzz", @"MM/dd/yy HH:m zzz",
                                 @"M/d/yy HH:m zzz", @"MM/d/yy HH:m zzz",
                                 @"M/dd/yyyy H:m zzz", @"MM/dd/yyyy H:m zzz",
                                 @"M/d/yyyy H:m zzz", @"MM/d/yyyy H:m zzz",
                                 @"M/dd/yy H:m zzz", @"MM/dd/yy H:m zzz",
                                 @"M/d/yy H:m zzz", @"MM/d/yy H:m zzz",
                                 @"M/dd/yyyy HH:mm zzz", @"MM/dd/yyyy HH:mm zzz",
                                 @"M/d/yyyy HH:mm zzz", @"MM/d/yyyy HH:mm zzz",
                                 @"M/dd/yy HH:mm zzz", @"MM/dd/yy HH:mm zzz",
                                 @"M/d/yy HH:mm zzz", @"MM/d/yy HH:mm zzz",
                                 @"M/dd/yyyy H:mm zzz", @"MM/dd/yyyy H:mm zzz",
                                 @"M/d/yyyy H:mm zzz", @"MM/d/yyyy H:mm zzz",
                                 @"M/dd/yy H:mm zzz", @"MM/dd/yy H:mm zzz",
                                 @"M/d/yy H:mm zzz", @"MM/d/yy H:mm zzz"};
IFormatProvider provider = CultureInfo.InvariantCulture.DateTimeFormat;
DateTimeOffset result = new DateTimeOffset();

do {
   conOut.WriteLine("Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),");
   conOut.Write("Then press Enter: ");
   input = conIn.ReadLine();
   conOut.WriteLine();
   try
   {
      result = DateTimeOffset.ParseExact(input, formats, provider,
                                         DateTimeStyles.AllowWhiteSpaces);
      break;
   }
   catch (FormatException)
   {
      Console.WriteLine("Unable to parse {0}.", input);
      tries++;
   }
} while (tries < 3);
if (tries >= 3)
   Console.WriteLine("Exiting application without parsing {0}", input);
else
   Console.WriteLine("{0} was converted to {1}", input, result.ToString());
// Some successful sample interactions with the user might appear as follows:
//    Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),
//    Then press Enter: 12/08/2007 6:54 -6:00
//
//    12/08/2007 6:54 -6:00 was converted to 12/8/2007 6:54:00 AM -06:00
//
//    Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),
//    Then press Enter: 12/8/2007 06:54 -06:00
//
//    12/8/2007 06:54 -06:00 was converted to 12/8/2007 6:54:00 AM -06:00
//
//    Enter a date, time, and offset (MM/DD/YYYY HH:MM +/-HH:MM),
//    Then press Enter: 12/5/07 6:54 -6:00
//
//    12/5/07 6:54 -6:00 was converted to 12/5/2007 6:54:00 AM -06:00

Remarks

The DateTimeOffset.ParseExact(String, String[], IFormatProvider, DateTimeStyles) method parses the string representation of a date that matches any one of the patterns assigned to the formats parameter. If the input string does not match any one of these patterns with any of the variations defined by the styles parameter, the method throws a FormatException. Aside from comparing input to multiple formatting patterns, this overload behaves identically to the DateTimeOffset.ParseExact(String, String, IFormatProvider, DateTimeStyles) method.

The formats parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of the input parameter. When the method is called, input must match one of these patterns. For details about valid formatting codes, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. If the matched element in formats includes the z, zz, or zzz custom format specifiers to indicate that an offset must be present in input, that offset must include either a negative sign or a positive sign. If the sign is missing, the method throws a FormatException.

Important

Using the formats parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. The example provides an illustration of this.

If the matched element in formats requires that input contain a date but not a time, the resulting DateTimeOffset object is assigned a time of midnight (0:00:00). If the matched element in formats requires that input contain a time but not a date, the resulting DateTimeOffset object is assigned the current date on the local system. If the matched element in formats does not require that input contain an offset, the offset of the resulting DateTimeOffset object depends on the value of the styles parameter. If styles includes AssumeLocal, the offset of the local time zone is assigned to the DateTimeOffset object. If styles includes AssumeUniversal, the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the DateTimeOffset object. If neither value is specified, the offset of the local time zone is used.

The particular date and time symbols and strings used in input are defined by the formatProvider parameter. The same is true for the precise format of input, if the matching element of formats is a standard format specifier string. The formatProvider parameter can be either of the following:

If formatprovider is null, the CultureInfo object that corresponds to the current culture is used.

The styles parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the DateTimeStyles enumeration are supported except NoCurrentDateDefault. The following table lists the effect of each supported member.

DateTimeStyles member Behavior
AdjustToUniversal Parses input and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the DateTimeOffset.ToUniversalTime method of the returned DateTimeOffset object.
AssumeLocal If the matched element in formats does not require that input contain an offset value, the returned DateTimeOffset object is given the offset of the local time zone. This is the default value.
AssumeUniversal If the matched element in formats does not require that input contain an offset value, the returned DateTimeOffset object is given the UTC offset (+00:00).
AllowInnerWhite Allows input to include inner white space not specified by format. Extra white space can appear between date and time components and within individual components (except the offset), and is ignored when parsing the string.
AllowLeadingWhite Allows input to include leading spaces not specified by formats. These are ignored when parsing the string.
AllowTrailingWhite Allows input to include trailing spaces not specified by formats. These are ignored when parsing the string.
AllowWhiteSpaces Allows input to include leading, trailing, and inner spaces not specified by formats. All extra white-space characters not specified in the matched element in formats are ignored when parsing the string.
None Indicates that additional white space is not permitted in input. White space must appear exactly as specified in a particular element of formats for a match to occur. This is the default behavior.
RoundtripKind Has no effect because the DateTimeOffset structure does not include a Kind property.

Notes to Callers

In the .NET Framework 4, the ParseExact method throws a FormatException if the string to be parsed contains an hour component and an AM/PM designator that are not in agreement. In the .NET Framework 3.5 and earlier versions, the AM/PM designator is ignored.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

ParseExact(String, String, IFormatProvider, DateTimeStyles)

Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs

Converts the specified string representation of a date and time to its DateTimeOffset equivalent using the specified format, culture-specific format information, and style. The format of the string representation must match the specified format exactly.

public static DateTimeOffset ParseExact (string input, string format, IFormatProvider formatProvider, System.Globalization.DateTimeStyles styles);
public static DateTimeOffset ParseExact (string input, string format, IFormatProvider? formatProvider, System.Globalization.DateTimeStyles styles);

Parameters

input
String

A string that contains a date and time to convert.

format
String

A format specifier that defines the expected format of input.

formatProvider
IFormatProvider

An object that supplies culture-specific formatting information about input.

styles
DateTimeStyles

A bitwise combination of enumeration values that indicates the permitted format of input.

Returns

An object that is equivalent to the date and time that is contained in the input parameter, as specified by the format, formatProvider, and styles parameters.

Exceptions

The offset is greater than 14 hours or less than -14 hours.

-or-

The styles parameter includes an unsupported value.

-or-

The styles parameter contains DateTimeStyles values that cannot be used together.

input is null.

-or-

format is null.

input is an empty string ("").

-or-

input does not contain a valid string representation of a date and time.

-or-

format is an empty string.

-or-

The hour component and the AM/PM designator in input do not agree.

Examples

The following example uses the DateTimeOffset.ParseExact(String, String, IFormatProvider, DateTimeStyles) method with standard and custom format specifiers, the invariant culture, and various DateTimeStyles values to parse several date and time strings.

string dateString, format;
DateTimeOffset result;
CultureInfo provider = CultureInfo.InvariantCulture;

// Parse date-only value with invariant culture and assume time is UTC.
dateString = "06/15/2008";
format = "d";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider,
                                      DateTimeStyles.AssumeUniversal);
   Console.WriteLine("'{0}' converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("'{0}' is not in the correct format.", dateString);
}

// Parse date-only value with leading white space.
// Should throw a FormatException because only trailing white space is
// specified in method call.
dateString = " 06/15/2008";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider,
                                      DateTimeStyles.AllowTrailingWhite);
   Console.WriteLine("'{0}' converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("'{0}' is not in the correct format.", dateString);
}

// Parse date and time value, and allow all white space.
dateString = " 06/15/   2008  15:15    -05:00";
format = "MM/dd/yyyy H:mm zzz";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider,
                                      DateTimeStyles.AllowWhiteSpaces);
   Console.WriteLine("'{0}' converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("'{0}' is not in the correct format.", dateString);
}

// Parse date and time and convert to UTC.
dateString = "  06/15/2008 15:15:30 -05:00";
format = "MM/dd/yyyy H:mm:ss zzz";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider,
                                      DateTimeStyles.AllowWhiteSpaces |
                                      DateTimeStyles.AdjustToUniversal);
   Console.WriteLine("'{0}' converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("'{0}' is not in the correct format.", dateString);
}
// The example displays the following output:
//    '06/15/2008' converts to 6/15/2008 12:00:00 AM +00:00.
//    ' 06/15/2008' is not in the correct format.
//    ' 06/15/   2008  15:15    -05:00' converts to 6/15/2008 3:15:00 PM -05:00.
//    '  06/15/2008 15:15:30 -05:00' converts to 6/15/2008 8:15:30 PM +00:00.

The following example uses a variety of DateTimeStyles values to parse an array of strings that are expected to conform to ISO 8601. As the output from the example shows, strings that are in the proper format fail to parse if:

Strings that do not specify a UTC offset are assumed to have the offset of the local time zone (in this case, -07:00) unless the DateTimeStyles.AssumeUniversal flag is supplied in the method call. In that case, they are assumed to be Universal Coordinated Time.

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      string[] dateStrings = { "2018-08-18T12:45:16.0000000Z",
                               "2018/08/18T12:45:16.0000000Z",
                               "2018-18-08T12:45:16.0000000Z",
                               "2018-08-18T12:45:16.0000000",                               
                               " 2018-08-18T12:45:16.0000000Z ",
                               "2018-08-18T12:45:16.0000000+02:00",
                               "2018-08-18T12:45:16.0000000-07:00" }; 
      
      ParseWithISO8601(dateStrings, DateTimeStyles.None);
      Console.WriteLine("\n-----\n");
      ParseWithISO8601(dateStrings, DateTimeStyles.AllowWhiteSpaces);
      Console.WriteLine("\n-----\n");
      ParseWithISO8601(dateStrings, DateTimeStyles.AdjustToUniversal);
      Console.WriteLine("\n-----\n");
      ParseWithISO8601(dateStrings, DateTimeStyles.AssumeLocal);
      Console.WriteLine("\n-----\n");
      ParseWithISO8601(dateStrings, DateTimeStyles.AssumeUniversal);   }

   private static void ParseWithISO8601(string[] dateStrings, DateTimeStyles styles)
   {   
      Console.WriteLine($"Parsing with {styles}:");
      foreach (var dateString in dateStrings)
      {
         try {
            var date = DateTimeOffset.ParseExact(dateString, "O", null, styles);
            Console.WriteLine($"   {dateString,-35} --> {date:yyyy-MM-dd HH:mm:ss.FF zzz}");
         }
         catch (FormatException)
         {
            Console.WriteLine($"   FormatException: Unable to convert '{dateString}'");
         }   
      } 
   }
}
// The example displays the following output:
//      Parsing with None:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 12:45:16 -07:00
//         FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00
//
//      -----
//
//      Parsing with AllowWhiteSpaces:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 12:45:16 -07:00
//         2018-08-18T12:45:16.0000000Z       --> 2018-08-18 12:45:16 +00:00
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00
//
//      -----
//
//      Parsing with AdjustToUniversal:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 19:45:16 +00:00
//         FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 10:45:16 +00:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 19:45:16 +00:00
//
//      -----
//
//      Parsing with AssumeLocal:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 12:45:16 -07:00
//         FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00
//
//      -----
//
//      Parsing with AssumeUniversal:
//         2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//         FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//         2018-08-18T12:45:16.0000000         --> 2018-08-18 12:45:16 +00:00
//         FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//         2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//         2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00

Remarks

The DateTimeOffset.ParseExact(String, String, IFormatProvider, DateTimeStyles) method parses the string representation of a date, which must be in the format defined by the format parameter. It also requires that the <Date>, <Time>, and <Offset> elements of the string representation of a date and time appear in the order specified by format. If the input string does not match the pattern of the format parameter, with any variations defined by the styles parameter, the method throws a FormatException. In contrast, the DateTimeOffset.Parse(String, IFormatProvider, DateTimeStyles) method parses the string representation of a date in any one of the formats recognized by the format provider's DateTimeFormatInfo object. Parse also allows the <Date>, <Time>, and <Offset> elements of the string representation of a date and time to appear in any order.

The format parameter is a string that contains either a single standard format specifier or one or more custom format specifiers that define the required pattern of the input parameter. For details about valid formatting codes, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. If format includes the z, zz, or zzz custom format specifiers to indicate that an offset must be present in input, that offset must include either a negative sign or a positive sign. If the sign is missing, the method throws a FormatException.

If format requires that input contain a date but not a time, the resulting DateTimeOffset object is assigned a time of midnight (0:00:00). If format requires that input contain a time but not a date, the resulting DateTimeOffset object is assigned the current date on the local system. If format does not require that input contain an offset, the offset of the resulting DateTimeOffset object depends on the value of the styles parameter. If styles includes AssumeLocal, the offset of the local time zone is assigned to the DateTimeOffset object. If styles includes AssumeUniversal, the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the DateTimeOffset object. If neither value is specified, the offset of the local time zone is used.

The particular date and time symbols and strings used in input are defined by the formatProvider parameter. The same is true for the precise format of input, if format is a standard format specifier string. The formatProvider parameter can be either of the following:

If formatprovider is null, the CultureInfo object that corresponds to the current culture is used.

The styles parameter defines whether white space is allowed in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the DateTimeStyles enumeration are supported except NoCurrentDateDefault. The following table lists the effect of each supported member.

DateTimeStyles member Behavior
AdjustToUniversal Parses input and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the DateTimeOffset.ToUniversalTime method of the returned DateTimeOffset object.
AssumeLocal If format does not require that input contain an offset value, the returned DateTimeOffset object is given the offset of the local time zone. This is the default value.
AssumeUniversal If format does not require that input contain an offset value, the returned DateTimeOffset object is given the UTC offset (+00:00).
AllowInnerWhite Allows input to include inner white space not specified by format. Extra white space can appear between date and time components and within individual components, and is ignored when parsing the string.
AllowLeadingWhite Allows input to include leading spaces not specified by format. These are ignored when parsing the string.
AllowTrailingWhite Allows input to include trailing spaces not specified by format. These are ignored when parsing the string.
AllowWhiteSpaces Allows input to include leading, trailing, and inner spaces not specified by format. All extra white-space characters not specified in format are ignored when parsing the string.
None Indicates that additional white space is not permitted in input. White space must appear exactly as specified in format. This is the default behavior.
RoundtripKind Has no effect because the DateTimeOffset structure does not include a Kind property.

Notes to Callers

In the .NET Framework 4, the ParseExact method throws a FormatException if the string to be parsed contains an hour component and an AM/PM designator that are not in agreement. In the .NET Framework 3.5 and earlier versions, the AM/PM designator is ignored.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

ParseExact(String, String, IFormatProvider)

Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs

Converts the specified string representation of a date and time to its DateTimeOffset equivalent using the specified format and culture-specific format information. The format of the string representation must match the specified format exactly.

public static DateTimeOffset ParseExact (string input, string format, IFormatProvider formatProvider);
public static DateTimeOffset ParseExact (string input, string format, IFormatProvider? formatProvider);

Parameters

input
String

A string that contains a date and time to convert.

format
String

A format specifier that defines the expected format of input.

formatProvider
IFormatProvider

An object that supplies culture-specific formatting information about input.

Returns

An object that is equivalent to the date and time that is contained in input as specified by format and formatProvider.

Exceptions

The offset is greater than 14 hours or less than -14 hours.

input is null.

-or-

format is null.

input is an empty string ("").

-or-

input does not contain a valid string representation of a date and time.

-or-

format is an empty string.

-or-

The hour component and the AM/PM designator in input do not agree.

Examples

The following example uses the DateTimeOffset.ParseExact(String, String, IFormatProvider) method with standard and custom format specifiers and the invariant culture to parse several date and time strings.

string dateString, format;
DateTimeOffset result;
CultureInfo provider = CultureInfo.InvariantCulture;

// Parse date-only value with invariant culture.
dateString = "06/15/2008";
format = "d";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider);
   Console.WriteLine("{0} converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("{0} is not in the correct format.", dateString);
}

// Parse date-only value without leading zero in month using "d" format.
// Should throw a FormatException because standard short date pattern of
// invariant culture requires two-digit month.
dateString = "6/15/2008";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider);
   Console.WriteLine("{0} converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("{0} is not in the correct format.", dateString);
}

// Parse date and time with custom specifier.
dateString = "Sun 15 Jun 2008 8:30 AM -06:00";
format = "ddd dd MMM yyyy h:mm tt zzz";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider);
   Console.WriteLine("{0} converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("{0} is not in the correct format.", dateString);
}

// Parse date and time with offset without offset//s minutes.
// Should throw a FormatException because "zzz" specifier requires leading
// zero in hours.
dateString = "Sun 15 Jun 2008 8:30 AM -06";
try
{
   result = DateTimeOffset.ParseExact(dateString, format, provider);
   Console.WriteLine("{0} converts to {1}.", dateString, result.ToString());
}
catch (FormatException)
{
   Console.WriteLine("{0} is not in the correct format.", dateString);
}
// The example displays the following output:
//    06/15/2008 converts to 6/15/2008 12:00:00 AM -07:00.
//    6/15/2008 is not in the correct format.
//    Sun 15 Jun 2008 8:30 AM -06:00 converts to 6/15/2008 8:30:00 AM -06:00.
//    Sun 15 Jun 2008 8:30 AM -06 is not in the correct format.

The following example parses an array of strings that are expected to conform to ISO 8601. As the output from the example shows, strings with leading or trailing spaces fail to parse successfully, as do strings with date and time elements that are out of range.

using System;

public class Example2
{
   public static void Main()
   {
      string[] dateStrings = { "2018-08-18T12:45:16.0000000Z",
                               "2018/08/18T12:45:16.0000000Z",
                               "2018-18-08T12:45:16.0000000Z",
                               " 2018-08-18T12:45:16.0000000Z ",
                               "2018-08-18T12:45:16.0000000+02:00",
                               "2018-08-18T12:45:16.0000000-07:00" }; 
      
      foreach (var dateString in dateStrings)
      {
         try {
            var date = DateTimeOffset.ParseExact(dateString, "O", null);
            Console.WriteLine($"{dateString,-35} --> {date:yyyy-MM-dd HH:mm:ss.FF zzz}");
         }
         catch (FormatException)
         {
            Console.WriteLine($"FormatException: Unable to convert '{dateString}'");
         }   
      } 
   }
}
// The example displays the following output:
//      2018-08-18T12:45:16.0000000Z        --> 2018-08-18 12:45:16 +00:00
//      FormatException: Unable to convert '2018/08/18T12:45:16.0000000Z'
//      FormatException: Unable to convert '2018-18-08T12:45:16.0000000Z'
//      FormatException: Unable to convert ' 2018-08-18T12:45:16.0000000Z '
//      2018-08-18T12:45:16.0000000+02:00   --> 2018-08-18 12:45:16 +02:00
//      2018-08-18T12:45:16.0000000-07:00   --> 2018-08-18 12:45:16 -07:00

Remarks

The ParseExact(String, String, IFormatProvider) method parses the string representation of a date, which must be in the format defined by the format parameter. It also requires that the <Date>, <Time>, and <Offset> elements of the string representation of a date and time appear in the order specified by format. If the input string does not match this format parameter, the method throws a FormatException. In contrast, the DateTimeOffset.Parse(String, IFormatProvider) method parses the string representation of a date in any one of the formats recognized by the format provider's DateTimeFormatInfo object. Parse also allows the <Date>, <Time>, and <Offset> elements of the string representation of a date and time to appear in any order.

The format parameter is a string that contains either a single standard format specifier or one or more custom format specifiers that define the required format of the input parameter. For details about valid formatting codes, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. If format includes the z, zz, or zzz custom format specifiers to indicate that an offset must be present in input, that offset must include either a negative sign or a positive sign. If the sign is missing, the method throws a FormatException.

If format requires that input contain a date but not a time, the resulting DateTimeOffset object is assigned a time of midnight (0:00:00). If format requires that input contain a time but not a date, the resulting DateTimeOffset object is assigned the current date on the local system. If format does not require that input contain an offset, the resulting DateTimeOffset object is assigned the time zone offset of the local system.

The particular date and time symbols and strings used in input are defined by the formatProvider parameter, as is the precise format of input if format is a standard format specifier string. The formatProvider parameter can be either of the following:

If formatprovider is null, the CultureInfo object that corresponds to the current culture is used.

Notes to Callers

In the .NET Framework 4, the ParseExact method throws a FormatException if the string to be parsed contains an hour component and an AM/PM designator that are not in agreement. In the .NET Framework 3.5 and earlier versions, the AM/PM designator is ignored.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

ParseExact(ReadOnlySpan<Char>, ReadOnlySpan<Char>, IFormatProvider, DateTimeStyles)

Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs

Converts a character span that represents a date and time to its DateTimeOffset equivalent using the specified format, culture-specific format information, and style. The format of the date and time representation must match the specified format exactly.

public static DateTimeOffset ParseExact (ReadOnlySpan<char> input, ReadOnlySpan<char> format, IFormatProvider? formatProvider, System.Globalization.DateTimeStyles styles = System.Globalization.DateTimeStyles.None);
public static DateTimeOffset ParseExact (ReadOnlySpan<char> input, ReadOnlySpan<char> format, IFormatProvider formatProvider, System.Globalization.DateTimeStyles styles = System.Globalization.DateTimeStyles.None);

Parameters

input
ReadOnlySpan<Char>

A character span that represents a date and time.

format
ReadOnlySpan<Char>

A character span that contains a format specifier that defines the expected format of input.

formatProvider
IFormatProvider

An object that provides culture-specific formatting information about input.

styles
DateTimeStyles

A bitwise combination of enumeration values that indicates the permitted format of input.

Returns

An object that is equivalent to the date and time that is contained in the input parameter, as specified by the format, formatProvider, and styles parameters.

Exceptions

The offset is greater than 14 hours or less than -14 hours. -or- The styles parameter includes an unsupported value. -or- The styles parameter contains DateTimeStyles values that cannot be used together.

input is an empty character span. -or- input does not contain a valid string representation of a date and time. -or- format is an empty character span. -or- The hour component and the AM/PM designator in input do not agree.

Remarks

This method parses a character span that represents a date, which must be in the format defined by the format parameter. It also requires that the <Date>, <Time>, and <Offset> elements of the string representation of a date and time appear in the order specified by format. If input does not match the format pattern, the method throws a FormatException. In contrast, the DateTimeOffset.Parse(ReadOnlySpan<Char>, IFormatProvider, DateTimeStyles) method parses the string representation of a date in any one of the formats recognized by the format provider's DateTimeFormatInfo object. Parse also allows the <Date>, <Time>, and <Offset> elements of the string representation of a date and time to appear in any order.

The format parameter is a character span that contains either a single-character standard format specifier or one or more custom format specifiers that define the required format of the input parameter. For details about valid formatting codes, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. If format includes the z, zz, or zzz custom format specifiers to indicate that an offset must be present in input, that offset must include either a negative sign or a positive sign. If the sign is missing, the method throws a FormatException.

If format requires that input contain a date but not a time, the resulting DateTimeOffset object is assigned a time of midnight (0:00:00). If format requires that input contain a time but not a date, the resulting DateTimeOffset object is assigned the current date on the local system. If format does not require that input contain an offset, the resulting DateTimeOffset object is assigned the time zone offset of the local system.

The particular date and time symbols and strings used in input are defined by the formatProvider parameter, as is the precise format of input if format is a standard format specifier. The formatProvider parameter can be either of the following:

If formatprovider is null, the CultureInfo object that corresponds to the current culture is used.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Standard 2.1

ParseExact(ReadOnlySpan<Char>, String[], IFormatProvider, DateTimeStyles)

Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs
Source:
DateTimeOffset.cs

Converts a character span that contains the string representation of a date and time to its DateTimeOffset equivalent using the specified formats, culture-specific format information, and style. The format of the date and time representation must match one of the specified formats exactly.

public static DateTimeOffset ParseExact (ReadOnlySpan<char> input, string[] formats, IFormatProvider? formatProvider, System.Globalization.DateTimeStyles styles = System.Globalization.DateTimeStyles.None);
public static DateTimeOffset ParseExact (ReadOnlySpan<char> input, string[] formats, IFormatProvider formatProvider, System.Globalization.DateTimeStyles styles = System.Globalization.DateTimeStyles.None);

Parameters

input
ReadOnlySpan<Char>

A character span that contains a date and time to convert.

formats
String[]

An array of format specifiers that define the expected formats of input.

formatProvider
IFormatProvider

An object that supplies culture-specific formatting information about input.

styles
DateTimeStyles

A bitwise combination of enumeration values that indicates the permitted format of input.

Returns

An object that is equivalent to the date and time that is contained in the input parameter, as specified by the formats, formatProvider, and styles parameters.

Exceptions

The offset is greater than 14 hours or less than -14 hours. -or- styles includes an unsupported value. -or- The styles parameter contains DateTimeStyles values that cannot be used together.

input is an empty character span. -or- input does not contain a valid string representation of a date and time. -or- No element of formats contains a valid format specifier. -or- The hour component and the AM/PM designator in input do not agree.

Remarks

This method parses a character span representing a date that matches any one of the patterns assigned to the formats parameter. If input does not match any one of these patterns with any of the variations defined by the styles parameter, the method throws a FormatException. Aside from comparing input to multiple formatting patterns, this overload behaves identically to the DateTimeOffset.ParseExact(ReadOnlySpan<Char>, ReadOnlySpan<Char>, IFormatProvider, DateTimeStyles) method.

The formats parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of the input parameter. When the method is called, input must match one of these patterns. For details about valid formatting codes, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. If the matched element in formats includes the z, zz, or zzz custom format specifiers to indicate that an offset must be present in input, that offset must include either a negative sign or a positive sign. If the sign is missing, the method throws a FormatException.

Important

Using the formats parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds.

If the matched element in formats requires that input contain a date but not a time, the resulting DateTimeOffset object is assigned a time of midnight (0:00:00). If the matched element in formats requires that input contain a time but not a date, the resulting DateTimeOffset object is assigned the current date on the local system. If the matched element in formats does not require that input contain an offset, the offset of the resulting DateTimeOffset object depends on the value of the styles parameter. If styles includes AssumeLocal, the offset of the local time zone is assigned to the DateTimeOffset object. If styles includes AssumeUniversal, the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the DateTimeOffset object. If neither value is specified, the offset of the local time zone is used.

The particular date and time symbols and strings used in input are defined by the formatProvider parameter. The same is true for the precise format of input, if the matching element of formats is a standard format specifier string. The formatProvider parameter can be either of the following:

If formatprovider is null, the CultureInfo object that corresponds to the current culture is used.

The styles parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the DateTimeStyles enumeration are supported except NoCurrentDateDefault. The following table lists the effect of each supported member.

DateTimeStyles member Behavior
AdjustToUniversal Parses input and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the DateTimeOffset.ToUniversalTime method of the returned DateTimeOffset object.
AssumeLocal If the matched element in formats does not require that input contain an offset value, the returned DateTimeOffset object is given the offset of the local time zone. This is the default value.
AssumeUniversal If the matched element in formats does not require that input contain an offset value, the returned DateTimeOffset object is given the UTC offset (+00:00).
AllowInnerWhite Allows input to include inner white space not specified by format. Extra white space can appear between date and time components and within individual components (except the offset), and is ignored when parsing the string.
AllowLeadingWhite Allows input to include leading spaces not specified by formats. These are ignored when parsing the string.
AllowTrailingWhite Allows input to include trailing spaces not specified by formats. These are ignored when parsing the string.
AllowWhiteSpaces Allows input to include leading, trailing, and inner spaces not specified by formats. All extra white-space characters not specified in the matched element in formats are ignored when parsing the string.
None Indicates that additional white space is not permitted in input. White space must appear exactly as specified in a particular element of formats for a match to occur. This is the default behavior.
RoundtripKind Has no effect because the DateTimeOffset structure does not include a Kind property.

Applies to

.NET 9 and other versions
Product Versions
.NET Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Standard 2.1