Rename Date to DateTime.

sdk/lib/core/date_time.dart

Index: sdk/lib/core/date_time.dart
diff --git a/sdk/lib/core/date.dart b/sdk/lib/core/date_time.dart
similarity index 64%
rename from sdk/lib/core/date.dart
rename to sdk/lib/core/date_time.dart
index d0c0f01d26819194ae0dcc130f6afaa7fe4f96b5..0894c45202d8ffd8a5cf032263ddfc413ac52530 100644
--- a/sdk/lib/core/date.dart
+++ b/sdk/lib/core/date_time.dart
@@ -5,13 +5,7 @@
 part of dart.core;
 
 /**
- * Date is the public interface to a point in time.
- *
- * It can represent time values that are at a distance of at most
- * 8,640,000,000,000,000ms (100,000,000 days) from epoch (1970-01-01 UTC). In
- * other words: [:millisecondsSinceEpoch.abs() <= 8640000000000000:].
- *
- * Also see [Stopwatch] for means to measure time-spans.
+ * Deprecated class. Please use [DateTime] instead.
  */
 abstract class Date implements Comparable {
   // Weekday constants that are returned by [weekday] method:
@@ -38,13 +32,6 @@ abstract class Date implements Comparable {
   static const int NOV = 11;
   static const int DEC = 12;
 
-  /**
-   * Constructs a [Date] instance based on the individual parts. The date is
-   * in the local time zone.
-   *
-   * [month] and [day] are one-based. For example
-   * [:new Date(1938, 1, 10):] represents the 10th of January 1938.
-   */
   factory Date(int year,
                [int month = 1,
                 int day = 1,
@@ -52,18 +39,9 @@ abstract class Date implements Comparable {
                 int minute = 0,
                 int second = 0,
                 int millisecond = 0]) {
-    return new _DateImpl(
-        year, month, day, hour, minute, second, millisecond, false);
+    return new DateTime(year, month, day, hour, minute, second, millisecond);
   }
 
-  /**
-   * Constructs a [Date] instance based on the individual parts. The date is
-   * in the UTC time zone.
-   *
-   * [month] and [day] are one-based. For example
-   * [:new Date.utc(1938, 1, 10):] represents the 10th of January 1938 in
-   * Coordinated Universal Time.
-   */
   factory Date.utc(int year,
                    [int month = 1,
                     int day = 1,
@@ -71,183 +49,163 @@ abstract class Date implements Comparable {
                     int minute = 0,
                     int second = 0,
                     int millisecond = 0]) {
-    return new _DateImpl(
-        year, month, day, hour, minute, second, millisecond, true);
+    return
+        new DateTime.utc(year, month, day, hour, minute, second, millisecond);
   }
 
-  /**
-   * Constructs a new [Date] instance with current date time value in the
-   * local time zone.
-   */
-  factory Date.now() => new _DateImpl.now();
+  factory Date.now() => new DateTime.now();
 
-  /**
-   * Constructs a new [Date] instance based on [formattedString].
-   */
   factory Date.fromString(String formattedString)
-      => new _DateImpl.fromString(formattedString);
+      => new DateTime.fromString(formattedString);
 
-  /**
-   * Constructs a new [Date] instance with the given [millisecondsSinceEpoch].
-   * If [isUtc] is false then the date is in the local time zone.
-   *
-   * The constructed [Date] represents
-   * 1970-01-01T00:00:00Z + [millisecondsSinceEpoch]ms in the given
-   * time zone (local or UTC).
-   */
-  // TODO(floitsch): the spec allows default values in interfaces, but our
-  // tools don't yet. Eventually we want to have default values here.
-  // TODO(lrn): Have two constructors instead of taking an optional bool.
   factory Date.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch,
                                           {bool isUtc: false}) {
-    return new _DateImpl.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
-                                                    isUtc);
+    return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+                                                   isUtc: isUtc);
   }
 
-  /**
-   * Returns true if [this] occurs at the same time as [other]. The
-   * comparison is independent of whether the time is utc or in the local
-   * time zone.
-   */
-  bool operator ==(Date other);
-  /**
-   * Returns true if [this] occurs before [other]. The comparison is independent
-   * of whether the time is utc or in the local time zone.
-   */
-  bool operator <(Date other);
-  /**
-   * Returns true if [this] occurs at the same time or before [other]. The
-   * comparison is independent of whether the time is utc or in the local
-   * time zone.
-   */
-  bool operator <=(Date other);
-  /**
-   * Returns true if [this] occurs after [other]. The comparison is independent
-   * of whether the time is utc or in the local time zone.
-   */
-  bool operator >(Date other);
-  /**
-   * Returns true if [this] occurs at the same time or after [other]. The
-   * comparison is independent of whether the time is utc or in the local
-   * time zone.
-   */
-  bool operator >=(Date other);
-
+  bool operator ==(DateTime other);
+  bool operator <(DateTime other);
+  bool operator <=(DateTime other);
+  bool operator >(DateTime other);
+  bool operator >=(DateTime other);
 
-  /**
-   * Returns [this] in the local time zone. Returns itself if it is already in
-   * the local time zone. Otherwise, this method is equivalent to
-   * [:new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
-   *                                       isUtc: false):].
-   */
-  Date toLocal();
 
-  /**
-   * Returns [this] in UTC. Returns itself if it is already in UTC. Otherwise,
-   * this method is equivalent to
-   * [:new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
-   *                                       isUtc: true):].
-   */
-  Date toUtc();
+  DateTime toLocal();
+  DateTime toUtc();
 
-  /**
-   * Returns the abbreviated time-zone name.
-   *
-   * Examples: [:"CET":] or [:"CEST":].
-   */
   String get timeZoneName;
-
-  /**
-   * The time-zone offset is the difference between local time and UTC. That is,
-   * the offset is positive for time zones west of UTC.
-   *
-   * Note, that JavaScript, Python and C return the difference between UTC and
-   * local time. Java, C# and Ruby return the difference between local time and
-   * UTC.
-   */
   Duration get timeZoneOffset;
 
-  /**
-   * Returns the year.
-   */
   int get year;
-
-  /**
-   * Returns the month into the year [1..12].
-   */
   int get month;
-
-  /**
-   * Returns the day into the month [1..31].
-   */
   int get day;
-
-  /**
-   * Returns the hour into the day [0..23].
-   */
   int get hour;
-
-  /**
-   * Returns the minute into the hour [0...59].
-   */
   int get minute;
-
-  /**
-   * Returns the second into the minute [0...59].
-   */
   int get second;
-
-  /**
-   * Returns the millisecond into the second [0...999].
-   */
   int get millisecond;
 
-  /**
-   * Returns the week day [MON..SUN]. In accordance with ISO 8601
-   * a week starts with Monday which has the value 1.
-   */
   int get weekday;
 
+  int get millisecondsSinceEpoch;
+
+  bool get isUtc;
+
+  String toString();
+
+  DateTime add(Duration duration);
+  DateTime subtract(Duration duration);
+  Duration difference(DateTime other);
+}
+
+/**
+ * Date is the public interface to a point in time.
+ *
+ * It can represent time values that are at a distance of at most
+ * 8,640,000,000,000,000ms (100,000,000 days) from epoch (1970-01-01 UTC). In
+ * other words: [:millisecondsSinceEpoch.abs() <= 8640000000000000:].
+ *
+ * Also see [Stopwatch] for means to measure time-spans.
+ */
+class DateTime implements Date {
+  // Weekday constants that are returned by [weekday] method:
+  static const int MON = 1;
+  static const int TUE = 2;
+  static const int WED = 3;
+  static const int THU = 4;
+  static const int FRI = 5;
+  static const int SAT = 6;
+  static const int SUN = 7;
+  static const int DAYS_IN_WEEK = 7;
+
+  // Month constants that are returned by the [month] getter.
+  static const int JAN = 1;
+  static const int FEB = 2;
+  static const int MAR = 3;
+  static const int APR = 4;
+  static const int MAY = 5;
+  static const int JUN = 6;
+  static const int JUL = 7;
+  static const int AUG = 8;
+  static const int SEP = 9;
+  static const int OCT = 10;
+  static const int NOV = 11;
+  static const int DEC = 12;
+
   /**
    * The milliseconds since 1970-01-01T00:00:00Z (UTC). This value is
    * independent of the time zone.
    *
    * See [Stopwatch] for means to measure time-spans.
    */
-  int get millisecondsSinceEpoch;
+  final int millisecondsSinceEpoch;
 
   /**
-   * True if this [Date] is set to UTC time.
+   * True if this [DateTime] is set to UTC time.
    */
-  bool get isUtc;
+  final bool isUtc;
 
   /**
-   * Returns a human readable string for this instance.
-   * The returned string is constructed for the time zone of this instance.
+   * Constructs a [DateTime] instance based on the individual parts. The date is
+   * in the local time zone.
+   *
+   * [month] and [day] are one-based. For example
+   * [:new DateTime(1938, 1, 10):] represents the 10th of January 1938.
    */
-  String toString();
+  // TODO(8042): This should be a redirecting constructor and not a factory.
+  factory DateTime(int year,
+           [int month = 1,
+            int day = 1,
+            int hour = 0,
+            int minute = 0,
+            int second = 0,
+            int millisecond = 0]) {
+    return new DateTime._internal(
+          year, month, day, hour, minute, second, millisecond, false);
+  }
 
   /**
-   * Returns a new [Date] with the [duration] added to this instance.
+   * Constructs a [DateTime] instance based on the individual parts. The date is
+   * in the UTC time zone.
+   *
+   * [month] and [day] are one-based. For example
+   * [:new DateTime.utc(1938, 1, 10):] represents the 10th of January 1938 in
+   * Coordinated Universal Time.
    */
-  Date add(Duration duration);
+  // TODO(8042): This should be a redirecting constructor and not a factory.
+  factory DateTime.utc(int year,
+                       [int month = 1,
+                        int day = 1,
+                        int hour = 0,
+                        int minute = 0,
+                        int second = 0,
+                        int millisecond = 0]) {
+    return new DateTime._internal(
+          year, month, day, hour, minute, second, millisecond, true);
+  }
 
   /**
-   * Returns a new [Date] with the [duration] subtracted from this instance.
+   * Constructs a new [DateTime] instance with current date time value in the
+   * local time zone.
    */
-  Date subtract(Duration duration);
+  // TODO(8042): This should be a redirecting constructor and not a factory.
+  factory DateTime.now() { return new DateTime._now(); }
 
   /**
-   * Returns a [Duration] with the difference of [:this:] and [other].
+   * Constructs a new [DateTime] instance based on [formattedString].
+   *
+   * The function parses a subset of ISO 8601. Examples of accepted strings:
+   *
+   * * `"2012-02-27 13:27:00"`
+   * * `"2012-02-27 13:27:00.123456z"`
+   * * `"20120227 13:27:00"`
+   * * `"20120227T132700"`
+   * * `"20120227"`
+   * * `"+20120227"`
+   * * `"2012-02-27T14Z"`
+   * * `"-123450101 00:00:00 Z"`: in the year -12345.
    */
-  Duration difference(Date other);
-}
-
-class _DateImpl implements Date {
-  final int millisecondsSinceEpoch;
-  final bool isUtc;
-
-  factory _DateImpl.fromString(String formattedString) {
+  factory DateTime.fromString(String formattedString) {
     // Read in (a subset of) ISO 8601.
     // Examples:
     //    - "2012-02-27 13:27:00"
@@ -294,8 +252,8 @@ class _DateImpl implements Date {
         throw new ArgumentError(formattedString);
       }
       if (addOneMillisecond) millisecondsSinceEpoch++;
-      return new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
-                                                 isUtc: isUtc);
+      return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+                                                     isUtc: isUtc);
     } else {
       throw new ArgumentError(formattedString);
     }
@@ -303,50 +261,102 @@ class _DateImpl implements Date {
 
   static const int _MAX_MILLISECONDS_SINCE_EPOCH = 8640000000000000;
 
-  _DateImpl.fromMillisecondsSinceEpoch(this.millisecondsSinceEpoch,
-                                       this.isUtc) {
+  /**
+   * Constructs a new [DateTime] instance with the given [millisecondsSinceEpoch].
+   * If [isUtc] is false then the date is in the local time zone.
+   *
+   * The constructed [DateTime] represents
+   * 1970-01-01T00:00:00Z + [millisecondsSinceEpoch]ms in the given
+   * time zone (local or UTC).
+   */
+  // TODO(lrn): Have two constructors instead of taking an optional bool.
+  DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch,
+                                      {bool isUtc: false})
+      : this.millisecondsSinceEpoch = millisecondsSinceEpoch,
+        this.isUtc = isUtc {
     if (millisecondsSinceEpoch.abs() > _MAX_MILLISECONDS_SINCE_EPOCH) {
       throw new ArgumentError(millisecondsSinceEpoch);
     }
     if (isUtc == null) throw new ArgumentError(isUtc);
   }
 
+  /**
+   * Returns true if [this] occurs at the same time as [other]. The
+   * comparison is independent of whether the time is utc or in the local
+   * time zone.
+   */
   bool operator ==(other) {
-    if (!(other is Date)) return false;
+    if (!(other is DateTime)) return false;
     return (millisecondsSinceEpoch == other.millisecondsSinceEpoch);
   }
 
-  bool operator <(Date other)
+  /**
+   * Returns true if [this] occurs before [other]. The comparison is independent
+   * of whether the time is utc or in the local time zone.
+   */
+  bool operator <(DateTime other)
       => millisecondsSinceEpoch < other.millisecondsSinceEpoch;
 
-  bool operator <=(Date other)
+  /**
+   * Returns true if [this] occurs at the same time or before [other]. The
+   * comparison is independent of whether the time is utc or in the local
+   * time zone.
+   */
+  bool operator <=(DateTime other)
       => millisecondsSinceEpoch <= other.millisecondsSinceEpoch;
 
-  bool operator >(Date other)
+  /**
+   * Returns true if [this] occurs after [other]. The comparison is independent
+   * of whether the time is utc or in the local time zone.
+   */
+  bool operator >(DateTime other)
       => millisecondsSinceEpoch > other.millisecondsSinceEpoch;
 
-  bool operator >=(Date other)
+  /**
+   * Returns true if [this] occurs at the same time or after [other]. The
+   * comparison is independent of whether the time is utc or in the local
+   * time zone.
+   */
+  bool operator >=(DateTime other)
       => millisecondsSinceEpoch >= other.millisecondsSinceEpoch;
 
-  int compareTo(Date other)
+  int compareTo(DateTime other)
       => millisecondsSinceEpoch.compareTo(other.millisecondsSinceEpoch);
 
   int get hashCode => millisecondsSinceEpoch;
 
-  Date toLocal() {
+  /**
+   * Returns [this] in the local time zone. Returns itself if it is already in
+   * the local time zone. Otherwise, this method is equivalent to
+   *
+   *     new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+   *                                             isUtc: false)
+   */
+  DateTime toLocal() {
     if (isUtc) {
-      return new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
-                                                 isUtc: false);
+      return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+                                                     isUtc: false);
     }
     return this;
   }
 
-  Date toUtc() {
+  /**
+   * Returns [this] in UTC. Returns itself if it is already in UTC. Otherwise,
+   * this method is equivalent to
+   *
+   *     new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+   *                                             isUtc: true)
+   */
+  DateTime toUtc() {
     if (isUtc) return this;
-    return new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
-                                               isUtc: true);
+    return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+                                                   isUtc: true);
   }
 
+  /**
+   * Returns a human readable string for this instance.
+   * The returned string is constructed for the time zone of this instance.
+   */
   String toString() {
     String fourDigits(int n) {
       int absN = n.abs();
@@ -382,47 +392,95 @@ class _DateImpl implements Date {
     }
   }
 
-  /** Returns a new [Date] with the [duration] added to [this]. */
-  Date add(Duration duration) {
+  /** Returns a new [DateTime] with the [duration] added to [this]. */
+  DateTime add(Duration duration) {
     int ms = millisecondsSinceEpoch;
-    return new Date.fromMillisecondsSinceEpoch(
+    return new DateTime.fromMillisecondsSinceEpoch(
         ms + duration.inMilliseconds, isUtc: isUtc);
   }
 
-  /** Returns a new [Date] with the [duration] subtracted from [this]. */
-  Date subtract(Duration duration) {
+  /** Returns a new [DateTime] with the [duration] subtracted from [this]. */
+  DateTime subtract(Duration duration) {
     int ms = millisecondsSinceEpoch;
-    return new Date.fromMillisecondsSinceEpoch(
+    return new DateTime.fromMillisecondsSinceEpoch(
         ms - duration.inMilliseconds, isUtc: isUtc);
   }
 
   /** Returns a [Duration] with the difference of [this] and [other]. */
-  Duration difference(Date other) {
+  Duration difference(DateTime other) {
     int ms = millisecondsSinceEpoch;
     int otherMs = other.millisecondsSinceEpoch;
     return new Duration(milliseconds: ms - otherMs);
   }
 
-  external _DateImpl(int year,
-                     int month,
-                     int day,
-                     int hour,
-                     int minute,
-                     int second,
-                     int millisecond,
-                     bool isUtc);
-  external _DateImpl.now();
+  external DateTime._internal(int year,
+                              int month,
+                              int day,
+                              int hour,
+                              int minute,
+                              int second,
+                              int millisecond,
+                              bool isUtc);
+  external DateTime._now();
   external static int _brokenDownDateToMillisecondsSinceEpoch(
       int year, int month, int day, int hour, int minute, int second,
       int millisecond, bool isUtc);
+
+  /**
+   * Returns the abbreviated time-zone name.
+   *
+   * Examples: [:"CET":] or [:"CEST":].
+   */
   external String get timeZoneName;
+
+  /**
+   * The time-zone offset is the difference between local time and UTC. That is,
+   * the offset is positive for time zones west of UTC.
+   *
+   * Note, that JavaScript, Python and C return the difference between UTC and
+   * local time. Java, C# and Ruby return the difference between local time and
+   * UTC.
+   */
   external Duration get timeZoneOffset;
+
+  /**
+   * Returns the year.
+   */
   external int get year;
+
+  /**
+   * Returns the month into the year [1..12].
+   */
   external int get month;
+
+  /**
+   * Returns the day into the month [1..31].
+   */
   external int get day;
+
+  /**
+   * Returns the hour into the day [0..23].
+   */
   external int get hour;
+
+  /**
+   * Returns the minute into the hour [0...59].
+   */
   external int get minute;
+
+  /**
+   * Returns the second into the minute [0...59].
+   */
   external int get second;
+
+  /**
+   * Returns the millisecond into the second [0...999].
+   */
   external int get millisecond;
+
+  /**
+   * Returns the week day [MON..SUN]. In accordance with ISO 8601
+   * a week starts with Monday which has the value 1.
+   */
   external int get weekday;
 }