DateTimeFormatter DateTimeFormatter DateTimeFormatter DateTimeFormatter DateTimeFormatter Class

Definition

Formats dates and times.

public : sealed class DateTimeFormatter : IDateTimeFormatter, IDateTimeFormatter2
struct winrt::Windows::Globalization::DateTimeFormatting::DateTimeFormatter : IDateTimeFormatter, IDateTimeFormatter2
public sealed class DateTimeFormatter : IDateTimeFormatter, IDateTimeFormatter2
Public NotInheritable Class DateTimeFormatter Implements IDateTimeFormatter, IDateTimeFormatter2
var dateTimeFormatter = new dateTimeFormatter(formatTemplate);
Attributes

Windows 10 requirements

Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

Use the DateTimeFormatter class to format a date.

// Format a date via a string template. Note that the order specifed in the string pattern does
// not determine the order of the parts of the formatted string. The user's language and region
// preferences will determine the pattern of the date returned based on the specified parts.

var mydatefmt = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("month day dayofweek year");
var dateToFormat = new Date();
var mydate = mydatefmt.format(dateToFormat);
// Format a date via a string template. Note that the order specifed in the string pattern does
// not determine the order of the parts of the formatted string. The user's language and region
// preferences will determine the pattern of the date returned based on the specified parts.

var formatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("month day dayofweek year");
DateTime dateToFormat = DateTime.Now;
var mydate = formatter.Format(dateToFormat);

Pattern grammarThe following grammar defines what is accepted for a pattern:

<pattern> ::= [<literal-text>] <datetime-pattern> [<literal-text>] |
              [<literal-text>] <datetime-pattern> <pattern>

<literal-text> ::= <literal-character>+

<literal-character> ::= [^{}] | "{openbrace}" | "{closebrace}"

<datetime-pattern> ::= <date-pattern> | <time-pattern>

<date-pattern> ::= <era> | <year> | <month> | <day> | <dayofweek>

<time-pattern> ::= <period> | <hour> | <minute> | <second> | <timezone>

<era> ::= "{era.abbreviated" [<ideal-length>] "}"

<year> ::= "{year.full" [<ideal-length>] "}" |
           "{year.abbreviated" [<ideal-length>] "}"

<month> ::= "{month.full}" |
            "{month.solo.full}" |
            "{month.abbreviated" [<ideal-length>] "}"
            "{month.solo.abbreviated" [<ideal-length>] "}"
            "{month.integer" [<ideal-length>] "}"

<dayofweek> ::= "{dayofweek.full}" |
                "{dayofweek.solo.full}" |
                "{dayofweek.abbreviated" [<ideal-length>] "}"
                "{dayofweek.solo.abbreviated" [<ideal-length>] "}"

<day> ::= "{day.integer" [<ideal-length>] "}"

<period> ::= "{period.abbreviated" [<ideal-length>] "}"

<hour> ::= "{hour.integer" [<ideal-length>] "}"

<minute> ::= "{minute.integer" [<ideal-length>] "}"

<second> ::= "{second.integer" [<ideal-length>] "}"

<timezone> ::= "{timezone.full}" |
                "{timezone.abbreviated" [<ideal-length>] "}"

<ideal-length> ::= "(" <non-zero-digit> ")"

<non-zero-digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

Template grammarThe following grammar defines what is accepted for a template:

<template> ::= <opt-whitespace> <date> <opt-whitespace> |
               <opt-whitespace> <time> <opt-whitespace> |
               <opt-whitespace> <specific-date> <whitespace> <time> <opt-whitespace> |
               <opt-whitespace> <time> <whitespace> <specific-date> <opt-whitespace> |
               <opt-whitespace> <relative-date> <whitespace> <time> <opt-whitespace> |
               <opt-whitespace> <time> <whitespace> <relative-date> <opt-whitespace>

<opt-whitespace> ::= [<whitespace>] 

<whitespace> ::= " "+ 

<date> ::= <year> | <month> | <day> | <month-year> | <relative-date> | <specific-date>

<relativedate> ::= <dayofweek> | <month-day> | <relative-longdate>

<specificdate> ::= <shortdate> | <longdate>

<month-day> ::= <month> <whitespace> <day> |
                <day> <whitespace> <month>

<relative-longdate> ::= <month> <whitespace> <day> <whitespace> <dayofweek> |
                        <month> <whitespace> <dayofweek> <whitespace> <day> |
                        <day> <whitespace> <month> <whitespace> <dayofweek> |
                        <day> <whitespace> <dayofweek> <whitespace> <month> |
                        <dayofweek> <whitespace> <day> <whitespace> <month> |
                        <dayofweek> <whitespace> <month> <whitespace> <day>

<month-year> ::= <month> <whitespace> <year> |
                 <year> <whitespace> <month>


<shortdate> ::= "shortdate" |
                <month> <whitespace> <day> <whitespace> <year> |
                <month> <whitespace> <year> <whitespace> <day> |
                <day> <whitespace> <month> <whitespace> <year> |
                <day> <whitespace> <year> <whitespace> <month> |
                <year> <whitespace> <day> <whitespace> <month> |
                <year> <whitespace> <month> <whitespace> <day>


<longdate> ::= "longdate" |
               <year> <whitespace> <month> <whitespace> <day> <whitespace> <dayofweek> |
               <year> <whitespace> <month> <whitespace> <dayofweek> <whitespace> <day> |
               <year> <whitespace> <day> <whitespace> <month> <whitespace> <dayofweek> |
               <year> <whitespace> <day> <whitespace> <dayofweek> <whitespace> <month> |
               <year> <whitespace> <dayofweek> <whitespace> <day> <whitespace> <month> |
               <year> <whitespace> <dayofweek> <whitespace> <month> <whitespace> <day> |
               <month> <whitespace> <year> <whitespace> <day> <whitespace> <dayofweek> |
               <month> <whitespace> <year> <whitespace> <dayofweek> <whitespace> <day> |
               <day> <whitespace> <year> <whitespace> <month> <whitespace> <dayofweek> |
               <day> <whitespace> <year> <whitespace> <dayofweek> <whitespace> <month> |
               <dayofweek> <whitespace> <year> <whitespace> <day> <whitespace> <month> |
               <dayofweek> <whitespace> <year> <whitespace> <month> <whitespace> <day> |
               <month> <whitespace> <day> <whitespace> <year> <whitespace> <dayofweek> |
               <month> <whitespace> <dayofweek> <whitespace> <year> <whitespace> <day> |
               <day> <whitespace> <month> <whitespace> <year> <whitespace> <dayofweek> |
               <day> <whitespace> <dayofweek> <whitespace> <year> <whitespace> <month> |
               <dayofweek> <whitespace> <day> <whitespace> <year> <whitespace> <month> |
               <dayofweek> <whitespace> <month> <whitespace> <year> <whitespace> <day> |
               <month> <whitespace> <day> <whitespace> <dayofweek> <whitespace> <year> |
               <month> <whitespace> <dayofweek> <whitespace> <day> <whitespace> <year> |
               <day> <whitespace> <month> <whitespace> <dayofweek> <whitespace> <year> |
               <day> <whitespace> <dayofweek> <whitespace> <month> <whitespace> <year> |
               <dayofweek> <whitespace> <day> <whitespace> <month> <whitespace> <year> |
               <dayofweek> <whitespace> <month> <whitespace> <day> <whitespace> <year>

<time> ::= <hour> | 
           <hour> <whitespace> <timezone> |
           <timezone> <whitespace> <hour> |
           <shorttime> |
           <longtime>

<shorttime> ::= "shorttime" |
                <hour> <whitespace> <minute> |
                <minute> <whitespace> <hour> |
                <timezone> <whitespace> <hour> <whitespace> <minute> |
                <timezone> <whitespace> <minute> <whitespace> <hour> |
                <hour> <whitespace> <timezone> <whitespace> <minute> |
                <minute> <whitespace> <timezone> <whitespace> <hour> |
                <hour> <whitespace> <minute> <whitespace> <timezone> |
                <minute> <whitespace> <hour> <whitespace> <timezone>

<longtime> ::= "longtime" |
               <hour> <whitespace> <minute> <whitespace> <second> |
               <hour> <whitespace> <second> <whitespace> <minute> |
               <minute> <whitespace> <hour> <whitespace> <second> |
               <minute> <whitespace> <second> <whitespace> <hour> |
               <second> <whitespace> <minute> <whitespace> <hour> |
               <second> <whitespace> <hour> <whitespace> <minute> |
               <timezone> <whitespace> <hour> <whitespace> <minute> <whitespace> <second> |
               <timezone> <whitespace> <hour> <whitespace> <second> <whitespace> <minute> |
               <timezone> <whitespace> <minute> <whitespace> <hour> <whitespace> <second> |
               <timezone> <whitespace> <minute> <whitespace> <second> <whitespace> <hour> |
               <timezone> <whitespace> <second> <whitespace> <minute> <whitespace> <hour> |
               <timezone> <whitespace> <second> <whitespace> <hour> <whitespace> <minute> |
               <hour> <whitespace> <timezone> <whitespace> <minute> <whitespace> <second> |
               <hour> <whitespace> <timezone> <whitespace> <second> <whitespace> <minute> |
               <minute> <whitespace> <timezone> <whitespace> <hour> <whitespace> <second> |
               <minute> <whitespace> <timezone> <whitespace> <second> <whitespace> <hour> |
               <second> <whitespace> <timezone> <whitespace> <minute> <whitespace> <hour> |
               <second> <whitespace> <timezone> <whitespace> <hour> <whitespace> <minute> |
               <hour> <whitespace> <minute> <whitespace> <timezone> <whitespace> <second> |
               <hour> <whitespace> <second> <whitespace> <timezone> <whitespace> <minute> |
               <minute> <whitespace> <hour> <whitespace> <timezone> <whitespace> <second> |
               <minute> <whitespace> <second> <whitespace> <timezone> <whitespace> <hour> |
               <second> <whitespace> <minute> <whitespace> <timezone> <whitespace> <hour> |
               <second> <whitespace> <hour> <whitespace> <timezone> <whitespace> <minute> |
               <hour> <whitespace> <minute> <whitespace> <second> <whitespace> <timezone> |
               <hour> <whitespace> <second> <whitespace> <minute> <whitespace> <timezone> |
               <minute> <whitespace> <hour> <whitespace> <second> <whitespace> <timezone> |
               <minute> <whitespace> <second> <whitespace> <hour> <whitespace> <timezone> |
               <second> <whitespace> <minute> <whitespace> <hour> <whitespace> <timezone> |
               <second> <whitespace> <hour> <whitespace> <minute> <whitespace> <timezone>

<year> ::= "year" | "year.full" | "year.abbreviated"

<month> ::= "month" | "month.full" | "month.abbreviated" | "month.numeric"

<day> ::= "day"

<dayofweek> ::= "dayofweek" | "dayofweek.full" | "dayofweek.abbreviated"

<hour> ::= "hour"

<minute> ::= "minute"

<second> ::= "second"

<timezone> ::= "timezone" | "timezone.full" | "timezone.abbreviated"

Remarks

Note

If your app passes language tags used in this class to any National Language Support functions, it must first convert the tags by calling ResolveLocaleName.

Some of the constructors for DateTimeFormatter take a formatTemplate string parameter that specifies the requested components to be formatted. This parameter can be either a format template or a format pattern. Format templates are convenient to use and provide formatting which is typical for the language, clock and calendar that you specify. Format patterns provide greater control of output than format templates. If you need formatting that is non-standard, use format patterns instead of templates.

In a format template, you specify the components (time, date, day of week, etc.) that you want to include in the formatted output. The formatter formats the components as appropriate for the specified language, clock and calendar. The order of the components in your template does not matter; the formatter orders the components according to the order shown in the format template language below.

Some commonly-used templates are listed in the following table. In templates with more than one component, the component may be any of the supported component variations and the components may be in any order. For example, "dayofweek.full year month.numeric day" is supported. (See below, after the Examples, for the grammar that defines valid templates.)

Important

You can't arbitrarily combine components and necessarily obtain a valid template. The only valid templates are those defined by the provided grammar.

Template
longdate
shortdate
longtime
shorttime
dayofweek
dayofweek.full
dayofweek.abbreviated
day
month
month.full
month.abbreviated
month.numeric
year
year.full
year.abbreviated
dayofweek day month year
dayofweek day month
day month year
day month
month year
hour
minute
second
hour minute second
hour minute
timezone
timezone.full
timezone.abbreviated
year month day hour

The following table shows sample output from formatters created with various values of template, language, and clock. The "Equivalent pattern" column provides a pattern that produces the same output as the template.

TemplateLanguageClockOutputEquivalent pattern
longdateen-US<not specified>‎Monday‎, ‎September‎ ‎2‎, ‎2013‎{dayofweek.full}‎, ‎{month.full}‎ ‎{day.integer}‎, ‎{year.full}
longdatefr-FR<not specified>lundi‎ ‎2‎ ‎septembre‎ ‎2013{dayofweek.full}‎ ‎{day.integer}‎ ‎{month.full}‎ ‎{year.full}
shortdateen-US<not specified>9‎/‎2‎/‎2013{month.integer}‎/‎{day.integer}‎/‎{year.full}
shortdatefr-FR<not specified>02‎/‎09‎/‎2013‎{day.integer(2)}‎/‎{month.integer(2)}‎/‎{year.full}
dayofweek month dayen-US<not specified>‎Monday‎, ‎September‎ ‎2{dayofweek.full}‎, ‎{month.full}‎ ‎{day.integer}
month day dayofweeken-US<not specified>‎Monday‎, ‎September‎ ‎2{dayofweek.full}‎, ‎{month.full}‎ ‎{day.integer}
longtimeen-US<not specified>‎6‎:‎01‎:‎24‎ ‎AM{hour.integer}‎:‎{minute.integer(2)}‎:‎{second.integer(2)}‎ ‎{period.abbreviated}
longtimeen-US24HourClock‎17‎:‎32‎:‎45{hour.integer}‎:‎{minute.integer(2)}‎:‎{second.integer(2)}
longtimefr-FR<not specified>17‎:‎32‎:‎45{hour.integer(2)}‎:‎{minute.integer(2)}‎:‎{second.integer(2)}
shorttimeen-US<not specified>6‎:‎01‎ ‎AM{hour.integer}‎:‎{minute.integer(2)}‎ ‎{period.abbreviated}
shorttimeen-US24HourClock17‎:‎32‎{hour.integer}‎:‎{minute.integer(2)}
shorttimefr-FR<not specified>17‎:‎32‎{hour.integer(2)}‎:‎{minute.integer(2)}

Format patterns are composed of a literal string with fields delimited by braces, such as "{day.numeric}/{month.numeric}/{year.full}". Some commonly-used fields are listed in the following table. (See below, after the Examples, for the grammar that defines valid patterns.)

Important

You can't arbitrarily combine fields and necessarily obtain a valid pattern. The only valid patterns are those defined by the provided grammar.

Format pattern field
{openbrace}
{closebrace}
{dayofweek.solo.<type>} where <type> is full / abbreviated / abbreviated(n)
{dayofweek.<type>} where <type> is full / abbreviated / abbreviated(n)
{day.<type>} where <type> is integer / integer(n)
{month.<type>} where <type> is full / abbreviated / abbreviated(n) / integer / integer(n)
{month.solo.<type>} where <type> is full / abbreviated / abbreviated(n)
{year.<type>} where <type> is full / abbreviated / abbreviated(n)
{era.<type>} where <type> is full / abbreviated / abbreviated(n)
{hour.<type>} where <type> is integer / integer(n)
{period.<type>} where <type> is full / abbreviated / abbreviated(n)
{minute.<type>} where <type> is integer / integer(n)
{second.<type>} where <type> is integer / integer(n)
{timezone.<type>} where <type> is full / abbreviated / abbreviated(n)

Note

  • Use {openbrace} or {closebrace} to specify that "{" or "}" appears as part of the literal string.
  • solo specifies the standalone form. For languages with genitive case distinctions, the genitive case is the unmarked case. To get the nominative case, use solo.
  • integer(2) for the fifth day of the month (for example) is "05", while integer(1) produces "5". integer produces the best n for a given language/calendar combination.
  • For years, full produces all digits ("2013"). abbreviated is synonymous with abbreviated(2), which is the 2-digit year for the gregorian calendar ("13"). (Other calendars may eventually use something else as the default; we have kept abbreviated to have the semantics of the best for a given language/calendar combination.) abbreviated(n) is truncated to the least significant n digits (for example, 2013 with n =1 is "3").

The following table shows sample output from formatters created with various values of pattern, language, and clock.

PatternLanguageClockOutput
{dayofweek.full}, ‎{month.full} {day.integer}, ‎{year.full}en-US<not specified>Monday, ‎September 2, ‎2013
{dayofweek.full}, ‎{day.integer(2)} ‎{month.full}, ‎{year.full}fr-FR<not specified>lundi, ‎02 ‎septembre, ‎2013
{month.integer}/‎{day.integer}/{year.full}en-US<not specified>9/‎2/2013
{month.integer}/‎{day.integer}/{year.abbreviated}en-US<not specified>9/‎2/13
{month.integer(2)}/‎{day.integer(2)}/{year.abbreviated}en-US<not specified>09/‎02/13
{hour.integer}:{minute.integer(2)}:{second.integer(2)} {period.abbreviated}en-US<not specified>6:01:24 AM
{hour.integer}:{minute.integer(2)}:{second.integer(2)} {period.abbreviated}en-US24HourClock17:32:45

Constructors

DateTimeFormatter(String) DateTimeFormatter(String) DateTimeFormatter(String) DateTimeFormatter(String) DateTimeFormatter(String)

Creates a DateTimeFormatter object that is initialized by a format template string.

DateTimeFormatter(String, IIterable<String>) DateTimeFormatter(String, IIterable<String>) DateTimeFormatter(String, IIterable<String>) DateTimeFormatter(String, IIterable<String>) DateTimeFormatter(String, IIterable<String>)

Creates a DateTimeFormatter object that is initialized by a format template string and language list.

DateTimeFormatter(String, IIterable<String>, String, String, String) DateTimeFormatter(String, IIterable<String>, String, String, String) DateTimeFormatter(String, IIterable<String>, String, String, String) DateTimeFormatter(String, IIterable<String>, String, String, String) DateTimeFormatter(String, IIterable<String>, String, String, String)

Creates a DateTimeFormatter object that is initialized by a format template string, language list, geographic region, calendar, and clock.

DateTimeFormatter(HourFormat, MinuteFormat, SecondFormat) DateTimeFormatter(HourFormat, MinuteFormat, SecondFormat) DateTimeFormatter(HourFormat, MinuteFormat, SecondFormat) DateTimeFormatter(HourFormat, MinuteFormat, SecondFormat) DateTimeFormatter(HourFormat, MinuteFormat, SecondFormat)

Creates a DateTimeFormatter object that is initialized with hour, minute, and second formats.

DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat)

Creates a DateTimeFormatter object that is initialized with year, month, day, and day of week formats.

DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>)

Creates a DateTimeFormatter object that is initialized with year, month, day, day of week, hour, minute, and second formats, and a language list.

DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>, String, String, String) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>, String, String, String) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>, String, String, String) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>, String, String, String) DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>, String, String, String)

Creates a DateTimeFormatter object with all formats and identifiers specified.

Properties

Calendar Calendar Calendar Calendar Calendar

Gets the calendar that is used when formatting dates.

Clock Clock Clock Clock Clock

Gets the clock that is used when formatting times.

GeographicRegion GeographicRegion GeographicRegion GeographicRegion GeographicRegion

Gets or sets the region that is used when formatting dates and times.

IncludeDay IncludeDay IncludeDay IncludeDay IncludeDay

Gets the DayFormat in the template.

IncludeDayOfWeek IncludeDayOfWeek IncludeDayOfWeek IncludeDayOfWeek IncludeDayOfWeek

Gets the DayOfWeekFormat in the template.

IncludeHour IncludeHour IncludeHour IncludeHour IncludeHour

Gets the HourFormat in the template.

IncludeMinute IncludeMinute IncludeMinute IncludeMinute IncludeMinute

Gets the MinuteFormat in the template.

IncludeMonth IncludeMonth IncludeMonth IncludeMonth IncludeMonth

Gets the MonthFormat in the template.

IncludeSecond IncludeSecond IncludeSecond IncludeSecond IncludeSecond

Gets the SecondFormat in the template.

IncludeYear IncludeYear IncludeYear IncludeYear IncludeYear

Gets the YearFormat in the template.

Languages Languages Languages Languages Languages

Gets the priority list of language identifiers that is used when formatting dates and times.

LongDate LongDate LongDate LongDate LongDate

Gets the DateTimeFormatter object that formats dates according to the user's choice of long date pattern.

LongTime LongTime LongTime LongTime LongTime

Gets the DateTimeFormatter object that formats times according to the user's choice of long time pattern.

NumeralSystem NumeralSystem NumeralSystem NumeralSystem NumeralSystem

Gets or sets the numbering system that is used to format dates and times.

Patterns Patterns Patterns Patterns Patterns

Gets the patterns corresponding to this template that are used when formatting dates and times.

ResolvedGeographicRegion ResolvedGeographicRegion ResolvedGeographicRegion ResolvedGeographicRegion ResolvedGeographicRegion

Gets the geographic region that was most recently used to format dates and times.

ResolvedLanguage ResolvedLanguage ResolvedLanguage ResolvedLanguage ResolvedLanguage

Gets the language that was most recently used to format dates and times.

ShortDate ShortDate ShortDate ShortDate ShortDate

Gets the DateTimeFormatter object that formats dates according to the user's choice of short date pattern.

ShortTime ShortTime ShortTime ShortTime ShortTime

Gets the DateTimeFormatter object that formats times according to the user's choice of short time pattern.

Template Template Template Template Template

Gets a string representation of this format template.

Methods

Format(DateTime) Format(DateTime) Format(DateTime) Format(DateTime) Format(DateTime)

Returns a string representation of the provided date and time.

Format(DateTime, String) Format(DateTime, String) Format(DateTime, String) Format(DateTime, String) Format(DateTime, String)

Returns a string that represents the given date and time in the given time zone, conforming to the template the formatter is currently using.

See Also