Export (0) Print
Expand All

DateTimeFormatInfo Class

Defines how DateTime values are formatted and displayed, depending on the culture.

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

public final class DateTimeFormatInfo implements ICloneable, IFormatProvider

This class contains information, such as date patterns, time patterns, and AM/PM designators. DateTime values are formatted using standard or custom patterns stored in the properties of a DateTimeFormatInfo object.

Using the DateTimeFormatInfo constructor directly in your application creates date/time information for the invariant culture only. The application uses the InvariantInfo property for a read-only version or the DateTimeFormatInfo constructor for a writable version. It is not possible to create a DateTimeFormatInfo object for a neutral culture.

To create a DateTimeFormatInfo object for a specific culture, the application creates a CultureInfo object for that culture and retrieves the CultureInfo.DateTimeFormat property. The date/time data obtained this way is applicable to the specific culture only.

To create a DateTimeFormatInfo object for the culture of the current thread, the application should use the CurrentInfo property.

The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the CultureInfo.UseUserOverride property is set to true, the properties of the CultureInfo.DateTimeFormat object, the CultureInfo.NumberFormat object, and the CultureInfo.TextInfo boject are also retrieved from the user settings. If the user settings are incompatible with the culture associated with the CultureInfo object, for example, if the selected calendar is not one of the calendars indicated by OptionalCalendars, the results of the methods and the values of the properties are undefined.

For versions of .NET Framework prior to version 2.0, if the CultureInfo.UseUserOverride property is set to true, the object reads each user-overridable property only when it is accessed for the first time. Because DateTimeFormatInfo has more than one user-overridable property, this "lazy initialization" can lead to an inconsistency between such properties when the application accesses one property, the user changes to another culture or overrides properties of the current user culture, then the application accesses a different property. For example, in a sequence like this, LongDatePattern can be accessed. Then the user can change patterns in the Control Panel. When accessed, ShortDatePattern follows the new settings. Similar inconsistencies can happen when the user chooses a different user culture, instead of just overriding one particular pattern.

In .NET Framework version 2.0 and later, DateTimeFormatInfo does not use "lazy initialization." Instead, it reads all user-overridable properties when it is created. There is still a small window of vulnerability since neither object creation nor the user override process is atomic and the relevant values can change in the midst of object creation. However, this situation should be extremely rare.

This change is particularly important in the case of serialization. .NET Framework version 2.0 and later persists all overridable settings, instead of just the ones that are accessed by the time serialization happens.

The application can replace standard patterns with custom patterns by setting the associated properties of a writable DateTimeFormatInfo object. To determine if a DateTimeFormatInfo object is writable, the application should use the IsReadOnly property.

The following table lists the standard DateTime format patterns associated with DateTimeFormatInfo properties. For more information, see Standard Date and Time Format Strings.

Format pattern

Associated property/description

d

ShortDatePattern

D

LongDatePattern

f

Full date and time (long date and short time)

F

FullDateTimePattern (long date and long time)

g

General (short date and short time)

G

General (short date and long time)

m, M

MonthDayPattern

o, O

Round-trip date/time pattern; with this format pattern, the formatting or parsing operation always uses the invariant culture

r, R

RFC1123Pattern; with this format pattern, the formatting or parsing operation always uses the invariant culture

s

SortableDateTimePattern (based on ISO 8601) using local time; with this format pattern, the formatting or parsing operation always uses the invariant culture

t

ShortTimePattern

T

LongTimePattern

u

UniversalSortableDateTimePattern using the format for universal time display; with this format pattern, the formatting or parsing operation always uses the invariant culture

U

Full date and time (long date and long time) using universal time

y, Y

YearMonthPattern

The following table lists the custom DateTime format patterns and their behavior. For more information, see Custom Date and Time Format Strings.

Format pattern

Description

d, %d

The day of the month. Single-digit days do not have a leading zero. The application specifies "%d" if the format pattern is not combined with other format patterns.

dd

The day of the month. Single-digit days have a leading zero.

ddd

The abbreviated name of the day of the week, as defined in AbbreviatedDayNames.

dddd

The full name of the day of the week, as defined in DayNames.

f, %f

The fraction of a second in single-digit precision. The remaining digits are truncated. The application specifies "%f" if the format pattern is not combined with other format patterns.

ff

The fraction of a second in double-digit precision. The remaining digits are truncated.

fff

The fraction of a second in three-digit precision. The remaining digits are truncated.

ffff

The fraction of a second in four-digit precision. The remaining digits are truncated.

fffff

The fraction of a second in five-digit precision. The remaining digits are truncated.

ffffff

The fraction of a second in six-digit precision. The remaining digits are truncated.

fffffff

The fraction of a second in seven-digit precision. The remaining digits are truncated.

F, %F

Displays the most significant digit of the seconds fraction. Nothing is displayed if the digit is zero. The application specifies "%F" if the format pattern is not combined with other format patterns.

FF

Displays the two most significant digits of the seconds fraction. However, trailing zeros, or two zero digits, are not displayed.

FFF

Displays the three most significant digits of the seconds fraction. However, trailing zeros, or three zero digits, are not displayed.

FFFF

Displays the four most significant digits of the seconds fraction. However, trailing zeros, or four zero digits, are not displayed.

FFFFF

Displays the five most significant digits of the seconds fraction. However, trailing zeros, or five zero digits, are not displayed.

FFFFFF

Displays the six most significant digits of the seconds fraction. However, trailing zeros, or six zero digits, are not displayed.

FFFFFFF

Displays the seven most significant digits of the seconds fraction. However, trailing zeros, or seven zero digits, are not displayed.

gg

The period or era. This pattern is ignored if the date to be formatted does not have an associated period or era string.

h, %h

The hour in a 12-hour clock. Single-digit hours do not have a leading zero. The application specifies "%h" if the format pattern is not combined with other format patterns.

hh

The hour in a 12-hour clock. Single-digit hours have a leading zero.

H, %H

The hour in a 24-hour clock. Single-digit hours do not have a leading zero. The application specifies "%H" if the format pattern is not combined with other format patterns.

HH

The hour in a 24-hour clock. Single-digit hours have a leading zero.

K

Different values of the Kind property, that is, Local, Utc, or Unspecified.

m, %m

The minute. Single-digit minutes do not have a leading zero. The application specifies "%m" if the format pattern is not combined with other format patterns.

mm

The minute. Single-digit minutes have a leading zero.

M, %M

The numeric month. Single-digit months do not have a leading zero. The application specifies "%M" if the format pattern is not combined with other format patterns.

MM

The numeric month. Single-digit months have a leading zero.

MMM

The abbreviated name of the month, as defined in AbbreviatedMonthNames.

MMMM

The full name of the month, as defined in MonthNames.

s, %s

The second. Single-digit seconds do not have a leading zero. The application specifies "%s" if the format pattern is not combined with other format patterns.

ss

The second. Single-digit seconds have a leading zero.

t, %t

The first character in the AM/PM designator defined in AMDesignator or PMDesignator, if any. The application specifies "%t" if the format pattern is not combined with other format patterns.

tt

The AM/PM designator defined in AMDesignator or PMDesignator, if any. Your application should use this format pattern for languages for which it is necessary to maintain the distinction between AM and PM. An example is Japanese, for which the AM and PM designators differ in the second character instead of the first character.

y, %y

The year without the century. If the year without the century is less than 10, the year is displayed with no leading zero. The application specifies "%y" if the format pattern is not combined with other format patterns.

yy

The year without the century. If the year without the century is less than 10, the year is displayed with a leading zero.

yyy

The year in three digits. If the year is less than 100, the year is displayed with a leading zero.

yyyy

The year in four or five digits (depending on the calendar used), including the century. Pads with leading zeros to get four digits. Thai Buddhist and Korean calendars have five-digit years. Users selecting the "yyyy" pattern see all five digits without leading zeros for calendars that have five digits. Exception: the Japanese and Taiwan calendars always behave as if "yy" is selected.

yyyyy

The year in five digits. Pads with leading zeros to get five digits. Exception: the Japanese and Taiwan calendars always behave as if "yy" is selected.

yyyyyy

The year in six digits. Pads with leading zeros to get six digits. Exception: the Japanese and Taiwan calendars always behave as if "yy" is selected. The pattern can be continued with a longer string of "y"s padding with more leading zeros.

z, %z

The time zone offset ("+" or "-" followed by the hour only). Single-digit hours do not have a leading zero. For example, Pacific Standard Time is "-8". The application specifies "%z" if the format pattern is not combined with other format patterns.

zz

The time zone offset ("+" or "-" followed by the hour only). Single-digit hours have a leading zero. For example, Pacific Standard Time is "-08".

zzz

The full time zone offset ("+" or "-" followed by the hour and minutes). Single-digit hours and minutes have leading zeros. For example, Pacific Standard Time is "-08:00".

:

The default time separator defined in TimeSeparator.

/

The default date separator defined in DateSeparator.

% c

Where c is a format pattern if used alone. To use format pattern "d", "f", "F", "h", "m", "s", "t", "y", "z", "H", or "M" by itself, the application specifies "%d", "%f", "%F", "%h", "%m", "%s", "%t", "%y", "%z", "%H", or "%M".

The "%" character can be omitted if the format pattern is combined with literal characters or other format patterns.

\ c

Where c is any character. Displays the character literally. To display the backslash character, the application should use "\\".

Only format patterns listed in the second table above can be used to create custom patterns. Standard format patterns listed in the first table are used only to create standard patterns. Custom patterns are at least two characters long, for example:

  • DateTime.ToString("d") returns the DateTime value; "d" is the standard short date pattern.

  • DateTime.ToString("%d") returns the day of the month; "%d" is a custom pattern.

  • DateTime.ToString("d ") returns the day of the month followed by a white-space character; "d " is a custom pattern.

The application can create a DateTimeFormatInfo object or a NumberFormatInfo object only for the invariant culture or for specific cultures, not for neutral cultures. For more information about the invariant culture, specific cultures, and neutral cultures, see the CultureInfo class.

This class implements the ICloneable interface to enable duplication of DateTimeFormatInfo objects. It also implements IFormatProvider to supply formatting information to applications.

The following code example prints out the different format patterns for the en-US culture. It also displays the value of the properties associated with the format patterns.

No code example is currently available or this language may not be supported.

System.Object
  System.Globalization.DateTimeFormatInfo

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

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.

.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

Community Additions

ADD
Show:
© 2014 Microsoft