DateTimeFormatInfo.SetAllDateTimePatterns Method (String(), Char)

 

Sets the custom date and time format strings that correspond to a specified standard format string.

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

<ComVisibleAttribute(False)>
Public Sub SetAllDateTimePatterns (
	patterns As String(),
	format As Char
)

Parameters

patterns
Type: System.String()

An array of custom format strings.

format
Type: System.Char

The standard format string associated with the custom format strings specified in the patterns parameter.

Exception Condition
ArgumentException

patterns is null or a zero-length array.

-or-

format is not a valid standard format string or is a standard format string whose patterns cannot be set.

ArgumentNullException

patterns has an array element whose value is null.

InvalidOperationException

This DateTimeFormatInfo object is read-only.

The SetAllDateTimePatterns method defines the custom format strings that correspond to a particular standard date and time format string. If a call to a date and time formatting method includes the standard date and time format string specified by format, the method uses the first element in the patterns array to define the format of the resulting string.

System_CAPS_warningWarning

The Parse and TryParse methods do not fully iterate all strings in patterns when parsing the string representation of a date and time. If you require a date and time string to have particular formats in a parsing operation, you should pass the array of valid formats to the DateTime.ParseExact(String, String(), IFormatProvider, DateTimeStyles), DateTimeOffset.ParseExact(String, String(), IFormatProvider, DateTimeStyles), DateTime.TryParseExact(String, String(), IFormatProvider, DateTimeStyles, DateTime), or DateTimeOffset.TryParseExact(String, String(), IFormatProvider, DateTimeStyles, DateTimeOffset) method.

You can define custom format strings that correspond to the "d", "D", "t", "T", and "y" or "Y" standard date and time format strings. If the value of format is any other standard format string, the SetAllDateTimePatterns method throws an ArgumentException.

If your custom date and time format strings include date separators, you should explicitly specify a date separator instead of relying on the parsing or formatting method that replaces the "/" custom format specifier with a particular date separator. For example, to obtain the pattern MM-DD-yyyy, use the pattern "MM-DD-yyyy".

The following example instantiates a CultureInfo object that represents the "en-US" (English - United States) culture and uses it to parse an array of date and time strings using the "Y" standard format string. It then uses the SetAllDateTimePatterns method to associate a new custom format string with the "Y" standard format string, and then attempts to parse the array of date and time strings. Output from the example demonstrates that the new custom format string is used in both the parsing and formatting operations.

Imports System.Globalization

Module Example
   Public Sub Main()
      ' Use standard en-US culture.
      Dim enUS As New CultureInfo("en-US")

      Dim values() As String = { "December 2010", "December, 2010",  
                                 "Dec-2010", "December-2010" } 

      Console.WriteLine("Supported Y/y patterns for {0} culture:", enUS.Name)
      For Each pattern In enUS.DateTimeFormat.GetAllDateTimePatterns("Y"c)
         Console.WriteLine("   " + pattern)
      Next 
      Console.WriteLine()

      ' Try to parse each date string using "Y" format specifier.
      For Each value In values
         Try
            Dim dat As Date = Date.ParseExact(value, "Y", enUS)
            Console.WriteLine(String.Format(enUS, "   Parsed {0} as {1:Y}", value, dat))
         Catch e As FormatException
            Console.WriteLine("   Cannot parse {0}", value)
         End Try   
      Next   
      Console.WriteLine()

      'Modify supported "Y" format.
      enUS.DateTimeFormat.SetAllDateTimePatterns( { "MMM-yyyy" } , "Y"c)

      Console.WriteLine("New supported Y/y patterns for {0} culture:", enUS.Name)
      For Each pattern In enUS.DateTimeFormat.GetAllDateTimePatterns("Y"c)
         Console.WriteLine("   " + pattern)
      Next 
      Console.WriteLine()

      ' Try to parse each date string using "Y" format specifier.
      For Each value In values
         Try
            Dim dat As Date = Date.ParseExact(value, "Y", enUS)
            Console.WriteLine(String.Format(enUS, "   Parsed {0} as {1:Y}", value, dat))
         Catch e As FormatException
            Console.WriteLine("   Cannot parse {0}", value)
         End Try   
      Next   
   End Sub
End Module
' The example displays the following output:
'       Supported Y/y patterns for en-US culture:
'          MMMM, yyyy
'       
'          Cannot parse December 2010
'          Parsed December, 2010 as December, 2010
'          Cannot parse Dec-2010
'          Cannot parse December-2010
'       
'       New supported Y/y patterns for en-US culture:
'          MMM-yyyy
'       
'          Cannot parse December 2010
'          Cannot parse December, 2010
'          Parsed Dec-2010 as Dec-2010
'          Cannot parse December-2010

Change History

Date

History

Reason

October 2010

Noted that the array of custom formats is not fully iterated in parsing operations.

Content bug fix.

June 2010

Revised extensively, replaced the example, and added exception information.

Customer feedback.

.NET Framework
Available since 2.0
Return to top
Show: