intl: Be more truthful about DateFormat's time zone support
DateFormat's documentation describes format specifiers for time zones
and even provides examples, but actually attempting to use a time
zone specifier will result in an UnimplementedError.
Explicitly state that time zone specifiers (and related methods and
constants) are not yet implemented and hide the unimplemented
examples from the generated dartdoc documentation.
PiperOrigin-RevId: 312216806
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 133fd7e..56e3dae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,8 @@
returning a value between 80 years in the past and 20 years in the future.
* Use package:clock to get the current date/time.
* Fix some more analysis complaints.
+ * Update documentation to indicate that time zone specifiers are not yet
+ implemented [#264][].
## 0.16.2
* Fix bug with dates in January being treated as ordinal. e.g. 2020-01-32 would
@@ -363,3 +365,4 @@
* Allow complex string literals in arguments (e.g. multi-line)
[#123]: https://github.com/dart-lang/intl/issues/123
+[#264]: https://github.com/dart-lang/intl/issues/264
diff --git a/lib/src/intl/date_format.dart b/lib/src/intl/date_format.dart
index e2c9033..282d3ef 100644
--- a/lib/src/intl/date_format.dart
+++ b/lib/src/intl/date_format.dart
@@ -108,13 +108,15 @@
/// 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
+/// 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
+//
+// TODO(https://github.com/dart-lang/intl/issues/74): Update table above.
///
/// Examples Using the US Locale:
///
@@ -156,13 +158,20 @@
/// 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'
///
+// TODO(https://github.com/dart-lang/intl/issues/74): Merge tables.
+//
+/// 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**:
@@ -190,12 +199,17 @@
///
/// 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
+//
+// TODO(https://github.com/dart-lang/intl/issues/74): Merge tables.
+//
+// NOT YET IMPLEMENTED
+// -------------------
+// 'yyyy.MM.dd G 'at' HH:mm:ss vvvv' 1996.07.10 AD at 15:08:56 Pacific Time
+// 'hh 'o''clock' a, zzzz' 12 o'clock PM, Pacific Daylight Time
+// 'K:mm a, vvv' 0:00 PM, PT
///
/// When parsing a date string using the abbreviated year pattern ('yy'),
/// DateFormat must interpret the abbreviated year relative to some
@@ -357,7 +371,7 @@
///
/// If [inputString] does not match our format, throws a [FormatException].
/// This will reject dates whose values are not strictly valid, even if the
- /// DateTime constructor will accept them. It will also rejct strings with
+ /// DateTime constructor will accept them. It will also reject strings with
/// additional characters (including whitespace) after a valid date. For
/// looser parsing, use [parse].
DateTime parseStrict(String inputString, [bool utc = false]) =>
@@ -471,9 +485,17 @@
DateFormat.j([locale]) : this('j', locale);
DateFormat.jm([locale]) : this('jm', locale);
DateFormat.jms([locale]) : this('jms', locale);
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
DateFormat.jmv([locale]) : this('jmv', locale);
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
DateFormat.jmz([locale]) : this('jmz', locale);
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
DateFormat.jv([locale]) : this('jv', locale);
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
DateFormat.jz([locale]) : this('jz', locale);
DateFormat.m([locale]) : this('m', locale);
DateFormat.ms([locale]) : this('ms', locale);
@@ -522,9 +544,17 @@
DateFormat add_j() => addPattern('j');
DateFormat add_jm() => addPattern('jm');
DateFormat add_jms() => addPattern('jms');
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
DateFormat add_jmv() => addPattern('jmv');
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
DateFormat add_jmz() => addPattern('jmz');
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
DateFormat add_jv() => addPattern('jv');
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
DateFormat add_jz() => addPattern('jz');
DateFormat add_m() => addPattern('m');
DateFormat add_ms() => addPattern('ms');
@@ -566,9 +596,17 @@
static const String HOUR = 'j';
static const String HOUR_MINUTE = 'jm';
static const String HOUR_MINUTE_SECOND = 'jms';
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
static const String HOUR_MINUTE_GENERIC_TZ = 'jmv';
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
static const String HOUR_MINUTE_TZ = 'jmz';
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
static const String HOUR_GENERIC_TZ = 'jv';
+ /// NOT YET IMPLEMENTED.
+ // TODO(https://github.com/dart-lang/intl/issues/74)
static const String HOUR_TZ = 'jz';
static const String MINUTE = 'm';
static const String MINUTE_SECOND = 'ms';
