DateFormat class

DateFormat is for formatting and parsing dates in a locale-sensitive manner.

It allows the user to choose from a set of standard date time formats as well as specify a customized pattern under certain locales. Date elements that vary across locales include month name, week name, field order, etc. We also allow the user to use any customized pattern to parse or format date-time strings under certain locales. Date elements that vary across locales include month name, weekname, field, order, etc.

Formatting dates in the default 'en_US' format does not require any initialization. e.g.

print(DateFormat.yMMMd().format(DateTime.now()));

But for other locales, the formatting data for the locale must be obtained. This can currently be done in one of three ways, determined by which library you import. In all cases, the 'initializeDateFormatting' method must be called and will return a future that is complete once the locale data is available. The result of the future isn't important, but the data for that locale is available to the date formatting and parsing once it completes.

The easiest option is that the data may be available locally, imported in a library that contains data for all the locales.

import 'package:intl/date_symbol_data_local.dart';
initializeDateFormatting('fr_FR', null).then((_) => runMyCode());

If we are running outside of a browser, we may want to read the data from files in the file system.

import 'package:intl/date_symbol_data_file.dart';
initializeDateFormatting('de_DE', null).then((_) => runMyCode());

If we are running in a browser, we may want to read the data from the server using the XmlHttpRequest mechanism.

import 'package:intl/date_symbol_data_http_request.dart';
initializeDateFormatting('pt_BR', null).then((_) => runMyCode());

Once we have the locale data, we need to specify the particular format. This library uses the ICU/JDK date/time pattern specification both for complete format specifications and also the abbreviated 'skeleton' form which can also adapt to different locales and is preferred where available.

Skeletons: These can be specified either as the ICU constant name or as the skeleton to which it resolves. The supported set of skeletons is as follows. For each skeleton there is a named constructor that can be used to create it. It's also possible to pass the skeleton as a string, but the constructor is preferred.

 ICU Name                   Skeleton
 --------                   --------
 DAY                          d
 ABBR_WEEKDAY                 E
 WEEKDAY                      EEEE
 ABBR_STANDALONE_MONTH        LLL
 STANDALONE_MONTH             LLLL
 NUM_MONTH                    M
 NUM_MONTH_DAY                Md
 NUM_MONTH_WEEKDAY_DAY        MEd
 ABBR_MONTH                   MMM
 ABBR_MONTH_DAY               MMMd
 ABBR_MONTH_WEEKDAY_DAY       MMMEd
 MONTH                        MMMM
 MONTH_DAY                    MMMMd
 MONTH_WEEKDAY_DAY            MMMMEEEEd
 ABBR_QUARTER                 QQQ
 QUARTER                      QQQQ
 YEAR                         y
 YEAR_NUM_MONTH               yM
 YEAR_NUM_MONTH_DAY           yMd
 YEAR_NUM_MONTH_WEEKDAY_DAY   yMEd
 YEAR_ABBR_MONTH              yMMM
 YEAR_ABBR_MONTH_DAY          yMMMd
 YEAR_ABBR_MONTH_WEEKDAY_DAY  yMMMEd
 YEAR_MONTH                   yMMMM
 YEAR_MONTH_DAY               yMMMMd
 YEAR_MONTH_WEEKDAY_DAY       yMMMMEEEEd
 YEAR_ABBR_QUARTER            yQQQ
 YEAR_QUARTER                 yQQQQ
 HOUR24                       H
 HOUR24_MINUTE                Hm
 HOUR24_MINUTE_SECOND         Hms
 HOUR                         j
 HOUR_MINUTE                  jm
 HOUR_MINUTE_SECOND           jms
 HOUR_MINUTE_GENERIC_TZ       jmv   (not yet implemented)
 HOUR_MINUTE_TZ               jmz   (not yet implemented)
 HOUR_GENERIC_TZ              jv    (not yet implemented)
 HOUR_TZ                      jz    (not yet implemented)
 MINUTE                       m
 MINUTE_SECOND                ms
 SECOND                       s

Examples Using the US Locale:

 Pattern                           Result
 ----------------                  -------
 DateFormat.yMd()                 -> 7/10/1996
 DateFormat('yMd')                -> 7/10/1996
 DateFormat.yMMMMd('en_US')       -> July 10, 1996
 DateFormat.jm()                  -> 5:08 PM
 DateFormat.yMd().add_jm()        -> 7/10/1996 5:08 PM
 DateFormat.Hm()                  -> 17:08 // force 24 hour time

Explicit Pattern Syntax: Formats can also be specified with a pattern string. This can be used for formats that don't have a skeleton available, but these will not adapt to different locales. For example, in an explicit pattern the letters 'H' and 'h' are available for 24 hour and 12 hour time formats respectively. But there isn't a way in an explicit pattern to get the behaviour of the 'j' skeleton, which prints 24 hour or 12 hour time according to the conventions of the locale, and also includes am/pm markers where appropriate. So it is preferable to use the skeletons.

The following characters are available in explicit patterns:

Symbol   Meaning                Presentation       Example
------   -------                ------------       -------
G        era designator         (Text)             AD
y        year                   (Number)           1996
M        month in year          (Text & Number)    July & 07
L        standalone month       (Text & Number)    July & 07
d        day in month           (Number)           10
c        standalone day         (Number)           10
h        hour in am/pm (1~12)   (Number)           12
H        hour in day (0~23)     (Number)           0
m        minute in hour         (Number)           30
s        second in minute       (Number)           55
S        fractional second      (Number)           978
E        day of week            (Text)             Tuesday
D        day in year            (Number)           189
a        am/pm marker           (Text)             PM
k        hour in day (1~24)     (Number)           24
K        hour in am/pm (0~11)   (Number)           0
Q        quarter                (Text)             Q3
'        escape for text        (Delimiter)        'Date='
''       single quote           (Literal)          'o''clock'

The following characters are reserved and currently are unimplemented:

Symbol   Meaning                Presentation       Example
------   -------                ------------       -------
z        time zone              (Text)             Pacific Standard Time
Z        time zone (RFC 822)    (Number)           -0800
v        time zone (generic)    (Text)             Pacific Time

The count of pattern letters determine the format.

Text:

• 5 pattern letters--use narrow form for standalone. Otherwise not used.
• 4 or more pattern letters--use full form,
• 3 pattern letters--use short or abbreviated form if one exists
• less than 3--use numeric form if one exists

Number: the minimum number of digits. Shorter numbers are zero-padded to this amount (e.g. if 'm' produces '6', 'mm' produces '06'). Year is handled specially; that is, if the count of 'y' is 2, the Year will be truncated to 2 digits. (e.g., if 'yyyy' produces '1997', 'yy' produces '97'.) Unlike other fields, fractional seconds are padded on the right with zero.

(Text & Number): 3 or over, use text, otherwise use number.

Any characters not in the pattern will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting text even though they are not enclosed in single quotes. In our current pattern usage, not all letters have meanings. But those unused letters are strongly discouraged to be used as quoted text without quotes, because we may use other letters as pattern characters in the future.

Examples Using the US Locale:

Format Pattern                    Result
--------------                    -------
"EEE, MMM d, ''yy"                Wed, Jul 10, '96
'h:mm a'                          12:08 PM
'yyyyy.MMMM.dd GGG hh:mm aaa'     01996.July.10 AD 12:08 PM

When parsing a date string using the abbreviated year pattern ('yy'), DateFormat must interpret the abbreviated year relative to some century. It does this by adjusting dates to be within 80 years before and 20 years after the time the parse function is called. For example, using a pattern of 'MM/dd/yy' and a DateFormat instance created on Jan 1, 1997, the string '01/11/12' would be interpreted as Jan 11, 2012 while the string '05/04/64' would be interpreted as May 4, 1964. During parsing, only strings consisting of exactly two digits will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string will be interpreted as its face value. Tests that parse two-digit years can control the current date with package:clock.

If the year pattern does not have exactly two 'y' characters, the year is interpreted literally, regardless of the number of digits. So using the pattern 'MM/dd/yyyy', '01/11/12' parses to Jan 11, 12 A.D.

Constructors

DateFormat([String? newPattern, String? locale])

Creates a new DateFormat, using the format specified by newPattern.

DateFormat.d([dynamic locale])

The named constructors for this class are all conveniences for creating instances using one of the known 'skeleton' formats, and having code completion support for discovering those formats. So,

DateFormat.E([dynamic locale])

DateFormat.EEEE([dynamic locale])

DateFormat.EEEEE([dynamic locale])

DateFormat.H([dynamic locale])

DateFormat.Hm([dynamic locale])

DateFormat.Hms([dynamic locale])

DateFormat.j([dynamic locale])

DateFormat.jm([dynamic locale])

DateFormat.jms([dynamic locale])

DateFormat.jmv([dynamic locale])

NOT YET IMPLEMENTED.

DateFormat.jmz([dynamic locale])

NOT YET IMPLEMENTED.

DateFormat.jv([dynamic locale])

NOT YET IMPLEMENTED.

DateFormat.jz([dynamic locale])

NOT YET IMPLEMENTED.

DateFormat.LLL([dynamic locale])

DateFormat.LLLL([dynamic locale])

DateFormat.M([dynamic locale])

DateFormat.m([dynamic locale])

DateFormat.Md([dynamic locale])

DateFormat.MEd([dynamic locale])

DateFormat.MMM([dynamic locale])

DateFormat.MMMd([dynamic locale])

DateFormat.MMMEd([dynamic locale])

DateFormat.MMMM([dynamic locale])

DateFormat.MMMMd([dynamic locale])

DateFormat.MMMMEEEEd([dynamic locale])

DateFormat.ms([dynamic locale])

DateFormat.QQQ([dynamic locale])

DateFormat.QQQQ([dynamic locale])

DateFormat.s([dynamic locale])

DateFormat.y([dynamic locale])

DateFormat.yM([dynamic locale])

DateFormat.yMd([dynamic locale])

DateFormat.yMEd([dynamic locale])

DateFormat.yMMM([dynamic locale])

DateFormat.yMMMd([dynamic locale])

DateFormat.yMMMEd([dynamic locale])

DateFormat.yMMMM([dynamic locale])

DateFormat.yMMMMd([dynamic locale])

DateFormat.yMMMMEEEEd([dynamic locale])

DateFormat.yQQQ([dynamic locale])

DateFormat.yQQQQ([dynamic locale])

Properties

dateOnly → bool

Does our format only date fields, and no time fields.

no setter

dateSymbols → DateSymbols

Return the DateSymbols information for the locale.

no setter

dateTimeConstructor ↔ _DateTimeConstructor

Allows specifying a different way of creating a DateTime instance for testing.

getter/setter pair

digitMatcher → RegExp

A regular expression which matches against digits for this locale.

no setter

hashCode → int

The hash code for this object.

no setter, inherited

locale → String

Return the locale code in which we operate, e.g. 'en_US' or 'pt'.

no setter

localeZero → String

For performance, keep the zero digit available.

no setter

localeZeroCodeUnit → int

For performance, keep the code unit of the zero digit available.

no setter

pattern → String?

Return the pattern that we use to format dates.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

useNativeDigits ↔ bool

Should we use native digits for printing DateTime, or ASCII.

getter/setter pair

usesAsciiDigits → bool

Does this use ASCII digits

no setter

usesNativeDigits → bool

no setter

Methods

add_d() → DateFormat

The 'add_*' methods append a particular skeleton to the format, or set it as the only format if none was previously set. These are primarily useful for creating compound formats. For example

add_E() → DateFormat

add_EEEE() → DateFormat

add_H() → DateFormat

add_Hm() → DateFormat

add_Hms() → DateFormat

add_j() → DateFormat

add_jm() → DateFormat

add_jms() → DateFormat

add_jmv() → DateFormat

NOT YET IMPLEMENTED.

add_jmz() → DateFormat

NOT YET IMPLEMENTED.

add_jv() → DateFormat

NOT YET IMPLEMENTED.

add_jz() → DateFormat

NOT YET IMPLEMENTED.

add_LLL() → DateFormat

add_LLLL() → DateFormat

add_m() → DateFormat

add_M() → DateFormat

add_Md() → DateFormat

add_MEd() → DateFormat

add_MMM() → DateFormat

add_MMMd() → DateFormat

add_MMMEd() → DateFormat

add_MMMM() → DateFormat

add_MMMMd() → DateFormat

add_MMMMEEEEd() → DateFormat

add_ms() → DateFormat

add_QQQ() → DateFormat

add_QQQQ() → DateFormat

add_s() → DateFormat

add_y() → DateFormat

add_yM() → DateFormat

add_yMd() → DateFormat

add_yMEd() → DateFormat

add_yMMM() → DateFormat

add_yMMMd() → DateFormat

add_yMMMEd() → DateFormat

add_yMMMM() → DateFormat

add_yMMMMd() → DateFormat

add_yMMMMEEEEd() → DateFormat

add_yQQQ() → DateFormat

add_yQQQQ() → DateFormat

addPattern(String? inputPattern, [String separator = ' ']) → DateFormat

Add inputPattern to this instance as a pattern.

format(DateTime date) → String

Return a string representing date formatted according to our locale and internal format.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

parse(String inputString, [bool utc = false]) → DateTime

Given user input, attempt to parse the inputString into the anticipated format, treating it as being in the local timezone.

parseLoose(String inputString, [bool utc = false]) → DateTime

Given user input, attempt to parse the inputString 'loosely' into the anticipated format, accepting some variations from the strict format.

parsePattern(String pattern) → List<_DateFormatField>

Parse the template pattern and return a list of field objects.

parseStrict(String inputString, [bool utc = false]) → DateTime

Given user input, attempt to parse the inputString into the anticipated format, treating it as being in the local timezone.

parseUtc(String inputString) → DateTime

Given user input, attempt to parse the inputString into the anticipated format, treating it as being in UTC. If inputString does not match our format, throws a FormatException.

parseUTC(String inputString) → DateTime

Given user input, attempt to parse the inputString into the anticipated format, treating it as being in UTC. If inputString does not match our format, throws a FormatException.

toString() → String

A string representation of this object.

inherited

tryParse(String inputString, [bool utc = false]) → DateTime?

Given user input, attempt to parse the inputString into the anticipated format, treating it as being in the local timezone.

tryParseLoose(String inputString, [bool utc = false]) → DateTime?

Given user input, attempt to parse the inputString 'loosely' into the anticipated format, accepting some variations from the strict format.

tryParseStrict(String inputString, [bool utc = false]) → DateTime?

Given user input, attempt to parse the inputString into the anticipated format, treating it as being in the local timezone.

tryParseUtc(String inputString) → DateTime?

Given user input, attempt to parse the inputString into the anticipated format, treating it as being in UTC. If inputString does not match our format, returns null.

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

allLocalesWithSymbols() → List<String>

Returns a list of all locales for which we have date formatting information.

localeExists(String? localeName) → bool

Return true if the locale exists, or if it is null. The null case is interpreted to mean that we use the default locale.

shouldUseNativeDigitsByDefaultFor(String locale) → bool

Should a new DateFormat for locale have useNativeDigits true.

useNativeDigitsByDefaultFor(String locale, bool value) → void

Indicate if a new DateFormat for locale should have useNativeDigits true.

Constants

ABBR_MONTH → const String

For each of the skeleton formats we also allow the use of the corresponding ICU constant names.

ABBR_MONTH_DAY → const String

ABBR_MONTH_WEEKDAY_DAY → const String

ABBR_QUARTER → const String

ABBR_STANDALONE_MONTH → const String

ABBR_WEEKDAY → const String

DAY → const String

HOUR → const String

HOUR24 → const String

HOUR24_MINUTE → const String

HOUR24_MINUTE_SECOND → const String

HOUR_GENERIC_TZ → const String

NOT YET IMPLEMENTED.

HOUR_MINUTE → const String

HOUR_MINUTE_GENERIC_TZ → const String

NOT YET IMPLEMENTED.

HOUR_MINUTE_SECOND → const String

HOUR_MINUTE_TZ → const String

NOT YET IMPLEMENTED.

HOUR_TZ → const String

NOT YET IMPLEMENTED.

MINUTE → const String

MINUTE_SECOND → const String

MONTH → const String

MONTH_DAY → const String

MONTH_WEEKDAY_DAY → const String

NUM_MONTH → const String

NUM_MONTH_DAY → const String

NUM_MONTH_WEEKDAY_DAY → const String

QUARTER → const String

SECOND → const String

STANDALONE_MONTH → const String

WEEKDAY → const String

YEAR → const String

YEAR_ABBR_MONTH → const String

YEAR_ABBR_MONTH_DAY → const String

YEAR_ABBR_MONTH_WEEKDAY_DAY → const String

YEAR_ABBR_QUARTER → const String

YEAR_MONTH → const String

YEAR_MONTH_DAY → const String

YEAR_MONTH_WEEKDAY_DAY → const String

YEAR_NUM_MONTH → const String

YEAR_NUM_MONTH_DAY → const String

YEAR_NUM_MONTH_WEEKDAY_DAY → const String

YEAR_QUARTER → const String