DateTimeFormatter DateTimeFormatter DateTimeFormatter DateTimeFormatter Class

Definition

public : sealed class DateTimeFormatter : IDateTimeFormatter, IDateTimeFormatter2public sealed class DateTimeFormatter : IDateTimeFormatter, IDateTimeFormatter2Public NotInheritable Class DateTimeFormatter Implements IDateTimeFormatter, IDateTimeFormatter2// You can use this class in JavaScript.

Attributes

ActivatableAttribute ContractVersionAttribute DualApiPartitionAttribute MarshalingBehaviorAttribute StaticAttribute ThreadingAttribute

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

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.)

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.

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.)

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

public : DateTimeFormatter(PlatForm::String formatTemplate)public DateTimeFormatter(String formatTemplate)Public Sub New(formatTemplate As String)// You can use this method in JavaScript.

public : DateTimeFormatter(PlatForm::String formatTemplate, IIterable<PlatForm::String> languages)public DateTimeFormatter(String formatTemplate, IEnumerable<String> languages)Public Sub New(formatTemplate As String, languages As IEnumerable<String>)// You can use this method in JavaScript.

public : DateTimeFormatter(PlatForm::String formatTemplate, IIterable<PlatForm::String> languages, PlatForm::String geographicRegion, PlatForm::String calendar, PlatForm::String clock)public DateTimeFormatter(String formatTemplate, IEnumerable<String> languages, String geographicRegion, String calendar, String clock)Public Sub New(formatTemplate As String, languages As IEnumerable<String>, geographicRegion As String, calendar As String, clock As String)// You can use this method in JavaScript.

public : DateTimeFormatter(HourFormat hourFormat, MinuteFormat minuteFormat, SecondFormat secondFormat)public DateTimeFormatter(HourFormat hourFormat, MinuteFormat minuteFormat, SecondFormat secondFormat)Public Sub New(hourFormat As HourFormat, minuteFormat As MinuteFormat, secondFormat As SecondFormat)// You can use this method in JavaScript.

public : DateTimeFormatter(YearFormat yearFormat, MonthFormat monthFormat, DayFormat dayFormat, DayOfWeekFormat dayOfWeekFormat)public DateTimeFormatter(YearFormat yearFormat, MonthFormat monthFormat, DayFormat dayFormat, DayOfWeekFormat dayOfWeekFormat)Public Sub New(yearFormat As YearFormat, monthFormat As MonthFormat, dayFormat As DayFormat, dayOfWeekFormat As DayOfWeekFormat)// You can use this method in JavaScript.

public : DateTimeFormatter(YearFormat yearFormat, MonthFormat monthFormat, DayFormat dayFormat, DayOfWeekFormat dayOfWeekFormat, HourFormat hourFormat, MinuteFormat minuteFormat, SecondFormat secondFormat, IIterable<PlatForm::String> languages)public DateTimeFormatter(YearFormat yearFormat, MonthFormat monthFormat, DayFormat dayFormat, DayOfWeekFormat dayOfWeekFormat, HourFormat hourFormat, MinuteFormat minuteFormat, SecondFormat secondFormat, IEnumerable<String> languages)Public Sub New(yearFormat As YearFormat, monthFormat As MonthFormat, dayFormat As DayFormat, dayOfWeekFormat As DayOfWeekFormat, hourFormat As HourFormat, minuteFormat As MinuteFormat, secondFormat As SecondFormat, languages As IEnumerable<String>)// You can use this method in JavaScript.

public : DateTimeFormatter(YearFormat yearFormat, MonthFormat monthFormat, DayFormat dayFormat, DayOfWeekFormat dayOfWeekFormat, HourFormat hourFormat, MinuteFormat minuteFormat, SecondFormat secondFormat, IIterable<PlatForm::String> languages, PlatForm::String geographicRegion, PlatForm::String calendar, PlatForm::String clock)public DateTimeFormatter(YearFormat yearFormat, MonthFormat monthFormat, DayFormat dayFormat, DayOfWeekFormat dayOfWeekFormat, HourFormat hourFormat, MinuteFormat minuteFormat, SecondFormat secondFormat, IEnumerable<String> languages, String geographicRegion, String calendar, String clock)Public Sub New(yearFormat As YearFormat, monthFormat As MonthFormat, dayFormat As DayFormat, dayOfWeekFormat As DayOfWeekFormat, hourFormat As HourFormat, minuteFormat As MinuteFormat, secondFormat As SecondFormat, languages As IEnumerable<String>, geographicRegion As String, calendar As String, clock As String)// You can use this method in JavaScript.

public : PlatForm::String Calendar { get; }public string Calendar { get; }Public ReadOnly Property Calendar As string// You can use this property in JavaScript.

public : PlatForm::String Clock { get; }public string Clock { get; }Public ReadOnly Property Clock As string// You can use this property in JavaScript.

public : PlatForm::String GeographicRegion { get; }public string GeographicRegion { get; }Public ReadOnly Property GeographicRegion As string// You can use this property in JavaScript.

public : DayFormat IncludeDay { get; }public DayFormat IncludeDay { get; }Public ReadOnly Property IncludeDay As DayFormat// You can use this property in JavaScript.

public : DayOfWeekFormat IncludeDayOfWeek { get; }public DayOfWeekFormat IncludeDayOfWeek { get; }Public ReadOnly Property IncludeDayOfWeek As DayOfWeekFormat// You can use this property in JavaScript.

public : HourFormat IncludeHour { get; }public HourFormat IncludeHour { get; }Public ReadOnly Property IncludeHour As HourFormat// You can use this property in JavaScript.

public : MinuteFormat IncludeMinute { get; }public MinuteFormat IncludeMinute { get; }Public ReadOnly Property IncludeMinute As MinuteFormat// You can use this property in JavaScript.

public : MonthFormat IncludeMonth { get; }public MonthFormat IncludeMonth { get; }Public ReadOnly Property IncludeMonth As MonthFormat// You can use this property in JavaScript.

public : SecondFormat IncludeSecond { get; }public SecondFormat IncludeSecond { get; }Public ReadOnly Property IncludeSecond As SecondFormat// You can use this property in JavaScript.

public : YearFormat IncludeYear { get; }public YearFormat IncludeYear { get; }Public ReadOnly Property IncludeYear As YearFormat// You can use this property in JavaScript.

public : IVectorView<string> Languages { get; }public IReadOnlyList<string> Languages { get; }Public ReadOnly Property Languages As IReadOnlyList<string>// You can use this property in JavaScript.

public : static DateTimeFormatter LongDate { get; }public static DateTimeFormatter LongDate { get; }Public Static ReadOnly Property LongDate As DateTimeFormatter// You can use this property in JavaScript.

public : static DateTimeFormatter LongTime { get; }public static DateTimeFormatter LongTime { get; }Public Static ReadOnly Property LongTime As DateTimeFormatter// You can use this property in JavaScript.

public : PlatForm::String NumeralSystem { get; set; }public string NumeralSystem { get; set; }Public ReadWrite Property NumeralSystem As string// You can use this property in JavaScript.

public : IVectorView<string> Patterns { get; }public IReadOnlyList<string> Patterns { get; }Public ReadOnly Property Patterns As IReadOnlyList<string>// You can use this property in JavaScript.

public : PlatForm::String ResolvedGeographicRegion { get; }public string ResolvedGeographicRegion { get; }Public ReadOnly Property ResolvedGeographicRegion As string// You can use this property in JavaScript.

public : PlatForm::String ResolvedLanguage { get; }public string ResolvedLanguage { get; }Public ReadOnly Property ResolvedLanguage As string// You can use this property in JavaScript.

public : static DateTimeFormatter ShortDate { get; }public static DateTimeFormatter ShortDate { get; }Public Static ReadOnly Property ShortDate As DateTimeFormatter// You can use this property in JavaScript.

public : static DateTimeFormatter ShortTime { get; }public static DateTimeFormatter ShortTime { get; }Public Static ReadOnly Property ShortTime As DateTimeFormatter// You can use this property in JavaScript.

public : PlatForm::String Template { get; }public string Template { get; }Public ReadOnly Property Template As string// You can use this property in JavaScript.

public : PlatForm::String Format(DateTime value)public string Format(DateTimeOffset value)Public Function Format(value As DateTimeOffset) As string// You can use this method in JavaScript.

public : PlatForm::String Format(DateTime datetime, PlatForm::String timeZoneId)public string Format(DateTimeOffset datetime, String timeZoneId)Public Function Format(datetime As DateTimeOffset, timeZoneId As String) As string// You can use this method in JavaScript.

See Also

• Date and time formatting sample
• Date and time formatting sample (Windows 10)