Polish Date formatting API.

lib/i18n/date_format.dart

 /**
  * Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
  * for details. All rights reserved. Use of this source code is governed by a
  * BSD-style license that can be found in the LICENSE file.
  *
- * DateTimeFormat is for formatting and parsing dates in a locale-sensitive 
+ * 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, weekname, field, order, etc.
  * //TODO(efortuna): Customized pattern system -- suggested by i18n needs
  * // feedback on appropriateness.
  * 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.
  *
@@ skipping 81 matching lines @@
  * runs are parsed specially. For example, the format "HHmmss" parses the input
  * text "123456" to 12:34:56, parses the input text "12345" to 1:23:45, and
  * fails to parse "1234". In other words, the leftmost field of the run is
  * flexible, while the others keep a fixed width. If the parse fails anywhere in
  * the run, then the leftmost field is shortened by one character, and the
  * entire run is parsed again. This is repeated until either the parse succeeds
  * or the leftmost field is one character in length. If the parse still fails at
  * that point, the parse of the run fails.
  */
 
-#library('DateTimeFormat');
+#library('DateFormat');
 
-class DateTimeFormat {
+class DateFormat {
 
   /** Definition of this object formats dates. */
   var formatDefinition;
 
   /**
-   * String indicating a language code with which the message is to be
-   * formatted (such as en-US).
+   * String indicating the locale code with which the message is to be
+   * formatted (such as en-CA).
    */
   String _locale;
 
   /** 
    * Date/Time format "skeleton" patterns. Also specifiable by String, but
-   * written this way so that they can be discoverable via autocomplete.
+   * written this way so that they can be discoverable via autocomplete. These
+   * follow the ICU syntax described at the top of the file. These skeletons can
+   * be combined and we will attempt to find the best format for each locale
+   * given the pattern.
+   * // TODO(efortuna): Hear back from i18n about Time Zones and the "core set"
+   * // of skeleton patterns.
    */
-  static final String Hm = 'Hm';          // HH:mm
-  static final String Hms = 'Hms';        // HH:mm:ss 
-  static final String M = 'M';            // L
-  static final String MEd = 'MEd';        // E, M/d
-  static final String MMM = 'MMM';        // LLL
-  static final String MMMEd = 'MMMEd';    // E, MMM d
-  static final String MMMMEd = 'MMMMEd';  // E, MMMM d
-  static final String MMMMd = 'MMMMd';    // MMMM d
-  static final String MMMd = 'MMMd';      // MMM d
-  static final String Md = 'Md';          // M/d
-  static final String d = 'd';            // d
-  static final String hm = 'hm';          // h:mm a
-  static final String ms = 'ms';          // mm:ss
-  static final String y = 'y';            // yyyy
-  static final String yM = 'yM';          // M/yyyy
-  static final String yMEd = 'yMEd';      // EEE, M/d/yyyy
-  static final String yMMM = 'yMMM';      // MMM yyyy
-  static final String yMMMEd = 'yMMMEd';  // EEE, MM d, yyyy
-  static final String yMMMM = 'yMMMM';    // MMMM yyyy
-  static final String yQ = 'yQ';          // Q yyyy
-  static final String yQQQ = 'yQQQ';      // QQQ yyyy
+                                          // Example of how this looks in the US
+                                          // locale.
+  static final String _Hm = 'Hm';          // HH:mm
+  static final String _Hms = 'Hms';        // HH:mm:ss 
+  static final String _M = 'M';            // L
+  static final String _MEd = 'MEd';        // E, M/d
+  static final String _MMM = 'MMM';        // LLL
+  static final String _MMMEd = 'MMMEd';    // E, MMM d
+  static final String _MMMMEd = 'MMMMEd';  // E, MMMM d
+  static final String _MMMMd = 'MMMMd';    // MMMM d
+  static final String _MMMd = 'MMMd';      // MMM d
+  static final String _Md = 'Md';          // M/d
+  static final String _d = 'd';            // d
+  static final String _hm = 'hm';          // h:mm a
+  static final String _ms = 'ms';          // mm:ss
+  static final String _y = 'y';            // yyyy
+  static final String _yM = 'yM';          // M/yyyy
+  static final String _yMEd = 'yMEd';      // EEE, M/d/yyyy
+  static final String _yMMM = 'yMMM';      // MMM yyyy
+  static final String _yMMMEd = 'yMMMEd';  // EEE, MM d, yyyy
+  static final String _yMMMM = 'yMMMM';    // MMMM yyyy
+  static final String _yQ = 'yQ';          // Q yyyy
+  static final String _yQQQ = 'yQQQ';      // QQQ yyyy
 
   /** Date/Time format patterns. */
-  // TODO(alanknight): There's a style question of whether to use fullDate or 
-  // FULL_DATE naming conventions.
-  static final int _fullDate = 0;
-  static final int _longDate = 1;
-  static final int _mediumDate = 2;
-  static final int _shortDate = 3;
-  static final int _fullTime = 4;
-  static final int _longTime = 5;
-  static final int _mediumTime = 6;
-  static final int _shortTime = 7;
-  static final int _fullDateTime = 8;
-  static final int _longDateTime = 9;
-  static final int _mediumDateTime = 10;
-  static final int _shortDateTime = 11;
+  // TODO(efortuna): This are just guesses of what a full date, long date is. 
+  // Do the proper homework on ICU to find the proper set "Hms"/"yMMd"
+  // applicable to each case.
+  static final String _fullDate = '$_y$_MMMMd';
+  static final String _longDate = _yMMMEd;
+  static final String _mediumDate = '$_y$_Md';
+  static final String _shortDate = _Md;
+  static final String _fullTime = '$_Hms a';
+  static final String _longTime = '$_Hms a zzzz';
+  static final String _mediumTime = _Hms;
+  static final String _shortTime = _Hm;
+  static final String _fullDateTime = '$_fullDate$_fullTime';
+  static final String _longDateTime = '$_logDate$_longTime';
+  static final String _mediumDateTime = '$_mediumDate$_mediumTime';
+  static final String _shortDateTime = '$_shortDate$_shortTime';
     
   /**
-   * Named constructors for each of the above values.
-   * These could probably be made shorter if we just set the format to the 
-   * constant and the parsing was lazy.
+   * Named constructors for the above values.
    */
-  DateTimeFormat.fullDate() : this.formatDefinition = _fullDate;
-  DateTimeFormat.longDate() : this.formatDefinition = _longDate;
-  DateTimeFormat.mediumDate() : this.formatDefinition = _mediumDate;
-  DateTimeFormat.shortDate() : this.formatDefinition = _shortDate;
-  DateTimeFormat.fullTime() : this.formatDefinition = _fullTime;
-  DateTimeFormat.longTime() : this.formatDefinition = _longTime;
-  DateTimeFormat.mediumTime() : this.formatDefinition = _mediumTime;
-  DateTimeFormat.shortTime() : this.formatDefinition = _shortTime;
-  DateTimeFormat.fullDateTime() : this.formatDefinition = _fullDateTime;
-  DateTimeFormat.longDateTime() : this.formatDefinition = _longDateTime;
-  DateTimeFormat.mediumDateTime() : this.formatDefinition = _mediumDateTime;
-  DateTimeFormat.shortDateTime() : this.formatDefinition = _shortDateTime;
+  DateFormat.Hm([this._locale]) : this.formatDefinition = _Hm;

[Jennifer Messerly, 2012/06/05 01:28:55]

minor nit: you shouldn't need "this." initializer lists.

+  DateFormat.Hms([this._locale]) : this.formatDefinition = _Hms;
+  DateFormat.M([this._locale]) : this.formatDefinition = _M;
+  DateFormat.MEd([this._locale]) : this.formatDefinition = _MEd;
+  DateFormat.MMM([this._locale]) : this.formatDefinition = _MMM;
+  DateFormat.MMMEd([this._locale]) : this.formatDefinition = _MMMEd;
+  DateFormat.MMMMEd([this._locale]) : this.formatDefinition = _MMMMEd;
+  DateFormat.MMMMd([this._locale]) : this.formatDefinition = _MMMMd;
+  DateFormat.MMMd([this._locale]) : this.formatDefinition = _MMMd;
+  DateFormat.Md([this._locale]) : this.formatDefinition = _Md;
+  DateFormat.d([this._locale]) : this.formatDefinition = _d;
+  DateFormat.hm([this._locale]) : this.formatDefinition = _hm;
+  DateFormat.ms([this._locale]) : this.formatDefinition = _ms;
+  DateFormat.y([this._locale]) : this.formatDefinition = _y;
+  DateFormat.yM([this._locale]) : this.formatDefinition = _yM;
+  DateFormat.yMEd([this._locale]) : this.formatDefinition = _yMEd;
+  DateFormat.yMMM([this._locale]) : this.formatDefinition = _yMMM;
+  DateFormat.yMMMEd([this._locale]) : this.formatDefinition = _yMMMEd;
+  DateFormat.yMMMM([this._locale]) : this.formatDefinition = _yMMMM;
+  DateFormat.yQ([this._locale]) : this.formatDefinition = _yQ;
+  DateFormat.yQQQ([this._locale]) : this.formatDefinition = _yQQQ;
+
+  DateFormat.fullDate([this._locale]) : this.formatDefinition = _fullDate;
+  DateFormat.longDate([this._locale]) : this.formatDefinition = _longDate;
+  DateFormat.mediumDate([this._locale]) : this.formatDefinition = _mediumDate;
+  DateFormat.shortDate([this._locale]) : this.formatDefinition = _shortDate;
+  DateFormat.fullTime([this._locale]) : this.formatDefinition = _fullTime;
+  DateFormat.longTime([this._locale]) : this.formatDefinition = _longTime;
+  DateFormat.mediumTime([this._locale]) : this.formatDefinition = _mediumTime;
+  DateFormat.shortTime([this._locale]) : this.formatDefinition = _shortTime;
+  DateFormat.fullDateTime([this._locale]) :
+      this.formatDefinition = _fullDateTime;
+  DateFormat.longDateTime([this._locale]) :
+      this.formatDefinition = _longDateTime;
+  DateFormat.mediumDateTime([this._locale]) :
+      this.formatDefinition = _mediumDateTime;
+  DateFormat.shortDateTime([this._locale]) :
+      this.formatDefinition = _shortDateTime;
   
   /**
    * Constructor accepts a [formatDefinition], which can be a String, one of the
    * predefined static forms, or a custom date format using the syntax described
    * above. An optional [_locale] can be provided for specifics of the language
    * locale to be used, otherwise, we will attempt to infer it (acceptable if
    * Dart is running on the client, we can infer from the browser).
    */
-  DateTimeFormat(this.formatDefinition, [this._locale]);
+  DateFormat(this.formatDefinition, [this._locale]);
 
   /**
    * Given user input, attempt to parse the [inputString] into the anticipated
    * format.
    */
   String parse(String inputString) {
     return inputString;
   }
 
  /**
   * Format the given [date] object according to preset pattern and current 
   * locale and return a formated string for the given date.
   */
   String format(Date date, [TimeZone timeZone]) {
     // TODO(efortuna): optional TimeZone argument? TimeZone is deprecated...
     return date.toString();
   }
+
+  /**
+   * Returns a date string indicating how long ago (3 hours, 2 minutes)
+   * something has happened or how long in the future something will happen
+   * given a [reference] Date relative to the current time.
+   */
+  String formatDuration(Date reference) {
+    return '';
+  }
+  
+  /**
+   * Formats a String indicating how long ago (negative [duration]) or how far
+   * in the future (positive [duration]) some time is with respect to a
+   * reference [date]. The [duration] is expressed in miliseconds.
+   */
+  String formatDurationFrom(num duration, Date date) {
+    return '';
+  }
 }