Rename Date to DateTime.

sdk/lib/core/date.dart

 // Copyright (c) 2011, 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.
 
 part of dart.core;

[Lasse Reichstein Nielsen, 2013/01/09 16:09:29]

Rename file to datetime.dart

[floitsch, 2013/01/22 20:23:39]

renamed to date_time.dart

 
 /**
  * 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.
  */
-abstract class Date implements Comparable {
+abstract class DateTime implements Comparable {

[Lasse Reichstein Nielsen, 2013/01/09 16:09:29]

Begin rant:
I still think it's a bad name. It's not the Time of a Date, but really a
DateAndTime. If you combine two concepts in one class, and can't find a single
name for it, maybe it isn't one concept and shouldn't be one class at all.

This is really a wibbly-wobbly timey-wimey thingy that combines an instant in
GMT time with a time-zone and some simplified proleptic-Gregorian calendar
concepts. It has no single concern that it covers, but it rather tries to
partially solve timestamps, time-zones and calendars, and does all three badly
(the first one least so, which is why I prefer Timestamp as name).

I don't think DateTime is better than Date apart from freeing up the "Date" name
for a *real* implementation.
I'd prefer "Time", but that also deserves a better class.
So does "Instant". And "PointInTime" is too long and odd.

So, let's do DateTime. At least we're not the first to do that, no matter how
bad it is.

   // 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;
 
   /**
-   * Constructs a [Date] instance based on the individual parts. The date is
+   * 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 Date(1938, 1, 10):] represents the 10th of January 1938.
+   * [:new DateTime(1938, 1, 10):] represents the 10th of January 1938.
    */
-  factory Date(int year,
+  factory DateTime(int year,
                [int month = 1,
                 int day = 1,
                 int hour = 0,
                 int minute = 0,
                 int second = 0,
                 int millisecond = 0]) {
     return new _DateImpl(
         year, month, day, hour, minute, second, millisecond, false);
   }
 
   /**
-   * Constructs a [Date] instance based on the individual parts. The date is
+   * 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 Date.utc(1938, 1, 10):] represents the 10th of January 1938 in
+   * [:new DateTime.utc(1938, 1, 10):] represents the 10th of January 1938 in
    * Coordinated Universal Time.
    */
-  factory Date.utc(int year,
+  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 _DateImpl(
         year, month, day, hour, minute, second, millisecond, true);
   }
 
   /**
-   * Constructs a new [Date] instance with current date time value in the
+   * Constructs a new [DateTime] instance with current date time value in the
    * local time zone.
    */
-  factory Date.now() => new _DateImpl.now();
+  factory DateTime.now() => new _DateImpl.now();
 
   /**
-   * Constructs a new [Date] instance based on [formattedString].
+   * Constructs a new [DateTime] instance based on [formattedString].
    */
-  factory Date.fromString(String formattedString)
+  factory DateTime.fromString(String formattedString)
       => new _DateImpl.fromString(formattedString);
 
   /**
-   * Constructs a new [Date] instance with the given [millisecondsSinceEpoch].
+   * Constructs a new [DateTime] instance with the given [millisecondsSinceEpoch].
    * If [isUtc] is false then the date is in the local time zone.
    *
-   * The constructed [Date] represents
+   * The constructed [DateTime] 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.

[Lasse Reichstein Nielsen, 2013/01/09 16:09:29]

Comment out-dated? We have a default value in the signature.

[floitsch, 2013/01/22 20:23:39]

Done.

   // TODO(lrn): Have two constructors instead of taking an optional bool.
-  factory Date.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch,
+  factory DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch,
                                           {bool isUtc: false}) {
     return new _DateImpl.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
                                                     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);
+  bool operator ==(DateTime 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);
+  bool operator <(DateTime 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);
+  bool operator <=(DateTime 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);
+  bool operator >(DateTime 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);
 
 
   /**
    * 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,
+   * [:new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
    *                                       isUtc: false):].
    */
-  Date toLocal();
+  DateTime toLocal();
 
   /**
    * Returns [this] in UTC. Returns itself if it is already in UTC. Otherwise,
    * this method is equivalent to
-   * [:new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+   * [:new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
    *                                       isUtc: true):].
    */
-  Date toUtc();
+  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,
@@ skipping 48 matching lines @@
 
   /**
    * 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;
 
   /**
-   * True if this [Date] is set to UTC time.
+   * True if this [DateTime] is set to UTC time.
    */
   bool get isUtc;
 
   /**
    * Returns a human readable string for this instance.
    * The returned string is constructed for the time zone of this instance.
    */
   String toString();
 
   /**
-   * Returns a new [Date] with the [duration] added to this instance.
+   * Returns a new [DateTime] with the [duration] added to this instance.
    */
-  Date add(Duration duration);
+  DateTime add(Duration duration);
 
   /**
-   * Returns a new [Date] with the [duration] subtracted from this instance.
+   * Returns a new [DateTime] with the [duration] subtracted from this instance.
    */
-  Date subtract(Duration duration);
+  DateTime subtract(Duration duration);
 
   /**
    * Returns a [Duration] with the difference of [:this:] and [other].
    */
-  Duration difference(Date other);
+  Duration difference(DateTime other);
 }
 
-class _DateImpl implements Date {
+class _DateImpl implements DateTime {
   final int millisecondsSinceEpoch;
   final bool isUtc;
 
   factory _DateImpl.fromString(String formattedString) {
     // Read in (a subset of) ISO 8601.
     // Examples:
     //    - "2012-02-27 13:27:00"
     //    - "2012-02-27 13:27:00.423z"
     //    - "20120227 13:27:00"
     //    - "20120227T132700"
@@ skipping 30 matching lines @@
         millisecond = 999;
       }
       // TODO(floitsch): we should not need to test against the empty string.
       bool isUtc = (match[8] != null) && (match[8] != "");
       int millisecondsSinceEpoch = _brokenDownDateToMillisecondsSinceEpoch(
           years, month, day, hour, minute, second, millisecond, isUtc);
       if (millisecondsSinceEpoch == null) {
         throw new ArgumentError(formattedString);
       }
       if (addOneMillisecond) millisecondsSinceEpoch++;
-      return new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+      return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
                                                  isUtc: isUtc);
     } else {
       throw new ArgumentError(formattedString);
     }
   }
 
   static const int _MAX_MILLISECONDS_SINCE_EPOCH = 8640000000000000;
 
   _DateImpl.fromMillisecondsSinceEpoch(this.millisecondsSinceEpoch,
                                        this.isUtc) {
     if (millisecondsSinceEpoch.abs() > _MAX_MILLISECONDS_SINCE_EPOCH) {
       throw new ArgumentError(millisecondsSinceEpoch);
     }
     if (isUtc == null) throw new ArgumentError(isUtc);
   }
 
   bool operator ==(other) {
-    if (!(other is Date)) return false;
+    if (!(other is DateTime)) return false;
     return (millisecondsSinceEpoch == other.millisecondsSinceEpoch);
   }
 
-  bool operator <(Date other)
+  bool operator <(DateTime other)
       => millisecondsSinceEpoch < other.millisecondsSinceEpoch;
 
-  bool operator <=(Date other)
+  bool operator <=(DateTime other)
       => millisecondsSinceEpoch <= other.millisecondsSinceEpoch;
 
-  bool operator >(Date other)
+  bool operator >(DateTime other)
       => millisecondsSinceEpoch > other.millisecondsSinceEpoch;
 
-  bool operator >=(Date other)
+  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() {
+  DateTime toLocal() {
     if (isUtc) {
-      return new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+      return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
                                                  isUtc: false);
     }
     return this;
   }
 
-  Date toUtc() {
+  DateTime toUtc() {
     if (isUtc) return this;
-    return new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+    return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
                                                isUtc: true);
   }
 
   String toString() {
     String fourDigits(int n) {
       int absN = n.abs();
       String sign = n < 0 ? "-" : "";
       if (absN >= 1000) return "$n";
       if (absN >= 100) return "${sign}0$absN";
       if (absN >= 10) return "${sign}00$absN";
@@ skipping 18 matching lines @@
     String min = twoDigits(minute);
     String sec = twoDigits(second);
     String ms = threeDigits(millisecond);
     if (isUtc) {
       return "$y-$m-$d $h:$min:$sec.${ms}Z";
     } else {
       return "$y-$m-$d $h:$min:$sec.$ms";
     }
   }
 
-  /** 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 static int _brokenDownDateToMillisecondsSinceEpoch(
       int year, int month, int day, int hour, int minute, int second,
       int millisecond, bool isUtc);
   external String get timeZoneName;
   external Duration get timeZoneOffset;
   external int get year;
   external int get month;
   external int get day;
   external int get hour;
   external int get minute;
   external int get second;
   external int get millisecond;
   external int get weekday;
 }