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(new DateFormat.yMMMd().format(new 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());
The code in example/basic/basic_example.dart shows a full example of using this mechanism.
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
HOUR_MINUTE_TZ jmz
HOUR_GENERIC_TZ jv
HOUR_TZ jz
MINUTE m
MINUTE_SECOND ms
SECOND s
Examples Using the US Locale:
Pattern Result
---------------- -------
new DateFormat.yMd() -> 7/10/1996
new DateFormat("yMd") -> 7/10/1996
new DateFormat.yMMMMd("en_US") -> July 10, 1996
new DateFormat.jm() -> 5:08 PM
new DateFormat.yMd().add_jm() -> 7/10/1996 5:08 PM
new 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
z time zone (Text) Pacific Standard Time
Z time zone (RFC 822) (Number) -0800
v time zone (generic) (Text) Pacific Time
Q quarter (Text) Q3
' escape for text (Delimiter) 'Date='
'' single quote (Literal) 'o''clock'
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
-------------- -------
"yyyy.MM.dd G 'at' HH:mm:ss vvvv" 1996.07.10 AD at 15:08:56 Pacific Time
"EEE, MMM d, ''yy" Wed, Jul 10, '96
"h:mm a" 12:08 PM
"hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time
"K:mm a, vvv" 0:00 PM, PT
"yyyyy.MMMMM.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 DateParse 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.
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.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 ])
- DateFormat.jmz([dynamic locale ])
- DateFormat.jv([dynamic locale ])
- DateFormat.jz([dynamic locale ])
- 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 only date fields, and no time fields. [...]
read-only
- dateSymbols → DateSymbols
-
Return the
DateSymbol
information for the locale. [...]read-only - digitMatcher → RegExp
-
A regular expression which matches against digits for this locale.
read-only
- locale → String
-
Return the locale code in which we operate, e.g. 'en_US' or 'pt'.
read-only
- localeZero → String
-
For performance, keep the zero digit available.
read-only
- localeZeroCodeUnit → int
-
For performance, keep the code unit of the zero digit available.
read-only
- pattern → dynamic
-
Return the pattern that we use to format dates.
read-only
- useNativeDigits ↔ bool
-
Should we use native digits for printing DateTime, or ASCII. [...]
read / write
- usesAsciiDigits → bool
-
Does this use ASCII digits
read-only
- usesNativeDigits → bool
-
read-only
- hashCode → int
-
The hash code for this object. [...]
read-only, inherited
- runtimeType → Type
-
A representation of the runtime type of the object.
read-only, inherited
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 -
add_jmz(
) → DateFormat -
add_jv(
) → DateFormat -
add_jz(
) → DateFormat -
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. -
formatDuration(
DateTime reference) → String - NOT YET IMPLEMENTED. [...]
-
formatDurationFrom(
Duration duration, DateTime date) → String - NOT YET IMPLEMENTED. [...]
-
parse(
String inputString, [ dynamic 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, [ dynamic 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, [ dynamic 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. [...] -
parseUtc(
String inputString) → DateTime -
Given user input, attempt to parse the
inputString
into the anticipated format, treating it as being in UTC. [...] -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a non-existent method or property is accessed. [...]
inherited
-
toString(
) → String -
Returns a string representation of this object.
inherited
Operators
-
operator ==(
dynamic 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(
dynamic 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) → dynamic -
Should a new DateFormat for
locale
have useNativeDigits true. [...] -
useNativeDigitsByDefaultFor(
String locale, bool value) → dynamic -
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.
'MMM'
- ABBR_MONTH_DAY → const String
-
'MMMd'
- ABBR_MONTH_WEEKDAY_DAY → const String
-
'MMMEd'
- ABBR_QUARTER → const String
-
'QQQ'
- ABBR_STANDALONE_MONTH → const String
-
'LLL'
- ABBR_WEEKDAY → const String
-
'E'
- DAY → const String
-
'd'
- HOUR → const String
-
'j'
- HOUR24 → const String
-
'H'
- HOUR24_MINUTE → const String
-
'Hm'
- HOUR24_MINUTE_SECOND → const String
-
'Hms'
- HOUR_GENERIC_TZ → const String
-
'jv'
- HOUR_MINUTE → const String
-
'jm'
- HOUR_MINUTE_GENERIC_TZ → const String
-
'jmv'
- HOUR_MINUTE_SECOND → const String
-
'jms'
- HOUR_MINUTE_TZ → const String
-
'jmz'
- HOUR_TZ → const String
-
'jz'
- MINUTE → const String
-
'm'
- MINUTE_SECOND → const String
-
'ms'
- MONTH → const String
-
'MMMM'
- MONTH_DAY → const String
-
'MMMMd'
- MONTH_WEEKDAY_DAY → const String
-
'MMMMEEEEd'
- NUM_MONTH → const String
-
'M'
- NUM_MONTH_DAY → const String
-
'Md'
- NUM_MONTH_WEEKDAY_DAY → const String
-
'MEd'
- QUARTER → const String
-
'QQQQ'
- SECOND → const String
-
's'
- STANDALONE_MONTH → const String
-
'LLLL'
- WEEKDAY → const String
-
'EEEE'
- YEAR → const String
-
'y'
- YEAR_ABBR_MONTH → const String
-
'yMMM'
- YEAR_ABBR_MONTH_DAY → const String
-
'yMMMd'
- YEAR_ABBR_MONTH_WEEKDAY_DAY → const String
-
'yMMMEd'
- YEAR_ABBR_QUARTER → const String
-
'yQQQ'
- YEAR_MONTH → const String
-
'yMMMM'
- YEAR_MONTH_DAY → const String
-
'yMMMMd'
- YEAR_MONTH_WEEKDAY_DAY → const String
-
'yMMMMEEEEd'
- YEAR_NUM_MONTH → const String
-
'yM'
- YEAR_NUM_MONTH_DAY → const String
-
'yMd'
- YEAR_NUM_MONTH_WEEKDAY_DAY → const String
-
'yMEd'
- YEAR_QUARTER → const String
-
'yQQQQ'