Refactor Date.

corelib/src/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.
 
 // Dart core library.
 
 /**
+ * Returns the local time-zone as defined in the official zone.tab file.
+ *
+ * Examples: [:"Europe/Andorra":], [:"America/Los_Angeles":] or
+ * [:"Europe/Paris":].
+ *
+ * If the underlying implementation is unable to get the correct timezone
+ * returns the offset to UTC. Examples: [:"GMT+03":], [:"GMT-02":], or
+ * [:"GTM+04:30":].
+ */
+String get localTimeZone() => DateImplementation.localTimeZone();
+/** Returns the current local time-zone's offset to UTC. */
+int get timeZoneOffsetInMinutes()

[Sean Eagan, 2012/05/14 14:43:51]

this should return a Duration instead of hard coded to minutes.  A good name
would be 'utcOffset'.

[floitsch, 2012/05/14 15:01:16]

good catch.

+    => DateImplementation.timeZoneOffsetInMinutes();
+/** Returns true if the local time-zone is currently in summer-savings mode. */
+bool get summerTimeSavingsIsActive()

[Sean Eagan, 2012/05/14 14:43:51]

it looks like this tries to combine the terms 'daylight savings time' and
'summer time' into one.  I think it would be better to just pick one and go with
it.  Also, I think name should have an 'is' prefix, e.g.:

isDaylightTime
isDaylightSavingsTime
isSummerTime
isDST (abbreviation as a last resort)

[floitsch, 2012/05/14 15:01:16]

my mistake. I wanted to write DaylightSavingsTimeIsActive.
The problem with "isDaylightSavingsTime" is that, for me, the name sounds like
it should be on a Date. Here we ask if the timzone is in daylightsavings mode.

[Sean Eagan, 2012/05/14 16:05:16]

oh, I thought this was an instance method on Date... but shouldn't it be ?  This
basically tells whether the current Date (i.e. new Date.now()) is in daylight
savings time, whereas it seems that would be useful to know for _any_ Date.

If it were to remain static, I wonder whether it should be a static method on
Date as opposed to a top-level.

In any case I still think 'isDaylightSavingsTime' is a better name, but maybe it
wouldn't be used enough to be a big deal anyway.

[floitsch, 2012/05/14 16:12:11]

Yes and no. It is both a property of a specific Date, as well as a property of
the machine. Basically the same as the Timezone itself.
That's where I wanted it to be, but Date is an interface and interfaces are not
allowed to have static methods.
Given that I don't see how to implement this in JS anyways I'm dropping this
predicate for now.

+    => DateImplementation.summerTimeSavingsIsActive();
+
+/**
  * Date is the public interface to a point in time.
  */
-interface Date extends Comparable default DateImplementation {
+interface Date extends Comparable, Hashable default DateImplementation {
   // Weekday constants that are returned by [weekday] method:
   static final int MON = 0;
   static final int TUE = 1;
   static final int WED = 2;
   static final int THU = 3;
   static final int FRI = 4;
   static final int SAT = 5;
   static final int SUN = 6;
   static final int DAYS_IN_WEEK = 7;
 
   // Month constants that are returned by the [month] getter.
   static final int JAN = 1;
   static final int FEB = 2;
   static final int MAR = 3;
   static final int APR = 4;
   static final int MAY = 5;
   static final int JUN = 6;
   static final int JUL = 7;
   static final int AUG = 8;
   static final int SEP = 9;
   static final int OCT = 10;
   static final int NOV = 11;
   static final int DEC = 12;
 
   /**
    * Constructs a [Date] instance based on the individual parts, in the
    * local time-zone.
    */
   Date(int year,
-       int month,
-       int day,
-       int hours,
-       int minutes,
-       int seconds,
-       int milliseconds);
+       [int month = 1,
+        int day = 1,
+        int hours = 0,
+        int minutes = 0,
+        int seconds = 0,
+        int milliseconds = 0]);
 
   /**
-   * Constructs a [Date] instance based on the individual parts.
-   * [timeZone] may not be [:null:].
-   */
-  Date.withTimeZone(int year,
-                    int month,
-                    int day,
-                    int hours,
-                    int minutes,
-                    int seconds,
-                    int milliseconds,
-                    TimeZone timeZone);
-
-  /**
-   * Constructs a new [Date] instance with current date time value.
-   * The [timeZone] of this instance is set to the local time-zone.
+   * Constructs a new [Date] instance with current date time value in the
+   * local time-zone.
    */
   Date.now();
 
   /**
    * Constructs a new [Date] instance based on [formattedString].
    */
   Date.fromString(String formattedString);
 
   /**
-   * Constructs a new [Date] instance with the given time zone. The given
-   * [timeZone] must not be [:null:].
+   * Constructs a new [Date] instance in the local time-zone.
    *
    * This constructor is the only one that doesn't need to be computations and
    * which can therefore be [:const:].
    *
    * The constructed [Date] represents 1970-01-01T00:00:00Z + [value]ms in
-   * the given [timeZone].
+   * the local time-zone.
    */
-  const Date.fromEpoch(int value, TimeZone timeZone);
+  const Date.fromEpoch(int value);
 
-  /**
-   * Returns a new [Date] in the given [targetTimeZone] time zone. The
-   * [value] of the new instance is equal to [:this.value:].
-   *
-   * This call is equivalent to
-   *  [:new Date.fromEpoch(this.value, targetTimeZone):].
-   */
-  Date changeTimeZone(TimeZone targetTimeZone);
+  bool operator <(Date other);
+  bool operator <=(Date other);
+  bool operator >=(Date other);
+  bool operator >(Date other);
 
   /**
    * Returns the year.
    */
   int get year();
 
   /**
    * Returns the month in the year [1..12].
    */
   int get month();
@@ skipping 24 matching lines @@
   int get milliseconds();
 
   /**
    * Returns the week day [MON..SUN]
    */
   int get weekday();
 
   /**
    * Returns milliseconds from 1970-01-01T00:00:00Z (UTC).
    *
-   * Note that this value is independent of [timeZone].
+   * Note that this value is independent of any time-zone.
    */
   final int value;
 
   /**
-   * Returns the timeZone of this instance.
-   */
-  final TimeZone timeZone;
-
-  /**
-   * Returns true if this [Date] is set to local time.
-   */
-  bool isLocalTime();
-
-  /**
-   * Returns true if this [Date] is set to UTC time.
-   * This is equivalent to [:this.timeZone.isUtc():].
-   */
-  bool isUtc();
-
-  /**
-   * Returns a human readable string for this instance.
-   * The returned string is constructed for the [timeZone] of this instance.
+   * Returns a human readable string for this instance. The returned string
+   * is constructed in the local time-zone and does not have any time-zone
+   * indication. Example: [:2012-05-14 14:20:25.442:]
    */
   String toString();
 
   /**
+  * Returns a human readable string for this instance in UTC time-zone.
+  * Example: [:2012-05-14 12:21:04.989Z:]

[floitsch, 2012/05/14 15:01:16]

Should we instead return a valid ISO 8601? It would only require to replace the
space with a "T":
2012-05-14T12:21:04.989Z

+  */
+  String toUTCString();

[Sean Eagan, 2012/05/14 14:43:51]

toUtcString

per the Dart style guide

[floitsch, 2012/05/14 15:01:16]

Done.

+
+  /**
    * Returns a new [Date] with the [duration] added to this instance.
    */
   Date add(Duration duration);
 
   /**
    * Returns a new [Date] with the [duration] subtracted from this instance.
    */
   Date subtract(Duration duration);
 
   /**
    * Returns a [Duration] with the difference of [:this:] and [other].
    */
   Duration difference(Date other);
 }