Make isUtc a getter, change some method names in 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.
 
 /**
  * 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: [:value.abs() <= 8640000000000000:].
+ * other words: [:millisecondsSinceEpoch.abs() <= 8640000000000000:].
+ *
+ * Also see [Stopwatch] for means to measure time-spans.
  */
 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 MON = 1;
+  static final int TUE = 2;
+  static final int WED = 3;
+  static final int THU = 4;
+  static final int FRI = 5;
+  static final int SAT = 6;
+  static final int SUN = 7;

[Lasse Reichstein Nielsen, 2012/06/19 14:32:18]

Are there definitions for JAN...DEC? Preferably one-based?

[floitsch, 2012/06/20 08:25:24]

one line below?

   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. The date is
    * in the local time zone if [isUtc] is false.
    */
   // TODO(floitsch): the spec allows default values in interfaces, but our
   // tools don't yet. Eventually we want to have default values here.
   Date(int year,
        [int month,

[Lasse Reichstein Nielsen, 2012/06/19 14:32:18]

Is "month" zero or one-based?
Are overflowing values allowed? (e.g, month 13 being January of the next year)

[floitsch, 2012/06/20 08:25:24]

1-based (added comment).
not yet, but I intend to allow it:
http://dartbug/2771

         int day,

[Lasse Reichstein Nielsen, 2012/06/19 14:32:18]

Should month and day really be optional? It makes little sense to me to create a
Date without specifying an actual date. 
At least give them default values of 1 and 1 when possible.
(Personally, I think you should drop the split between Date and
DateImplementation, and just include the implementation here - there won't be
any other (non-test) implementation of Date anyway).

[floitsch, 2012/06/20 08:25:24]

See http://dartbug/2582.
Apparently requiring month and day is less useful.
They all default to the smallest valid value. (which would be 1 and 1).
Another CL.

-        int hours,
-        int minutes,
-        int seconds,
-        int milliseconds,
+        int hour,
+        int minute,
+        int second,
+        int millisecond,
         bool isUtc]);
 
   /**
    * 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 [value]. If [isUtc] is
-   * false then the date is in the local time zone.
+   * 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 + [value]ms in
-   * the given time zone (local or UTC).
+   * 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.
-  Date.fromEpoch(int value, [bool isUtc]);
+  Date.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch, [bool 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.
@@ skipping 14 matching lines @@
    * 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);
 
 
   /**
    * 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.fromEpoch(this.value, isUtc: false):].
+   * [:new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch, false):].
    */
   Date toLocal();
 
   /**
    * Returns [this] in UTC. Returns itself if it is already in UTC. Otherwise,
    * this method is equivalent to
-   * [:new Date.fromEpoch(this.value, isUtc: true):].
+   * [:new Date.fromMillisecondsSinceEpoch(millisecondsSinceEpoch, true):].
    */
   Date toUtc();
 
   /**
    * Returns the abbreviated time-zone name.
    *
    * Examples: [:"CET":] or [:"CEST":].
    */
   String get timeZoneName();
 
@@ skipping 16 matching lines @@
    * Returns the month in the year [1..12].
    */
   int get month();
 
   /**
    * Returns the day in the month [1..31].
    */
   int get day();
 
   /**
-   * Returns the number of hours [0..23].
+   * Returns the hour in the day [0..23].

[Lasse Reichstein Nielsen, 2012/06/19 14:32:18]

"in" -> "into". There are always 24 hours in the day :)

[floitsch, 2012/06/20 08:25:24]

Done.

    */
-  int get hours();
+  int get hour();
 
   /**
-   * Returns the number of minutes [0...59].
+   * Returns the minute in the hour [0...59].

[Lasse Reichstein Nielsen, 2012/06/19 14:32:18]

"in" -> "into" again.

[floitsch, 2012/06/20 08:25:24]

Done.

    */
-  int get minutes();
+  int get minute();
 
   /**
-   * Returns the number of seconds [0...59].
+   * Returns the second in the minute [0...59].

[Lasse Reichstein Nielsen, 2012/06/19 14:32:18]

And again.
We are absolutely certain we won't need leap seconds?

[floitsch, 2012/06/20 08:25:24]

I think so.
If leap-seconds are an issue some systems (for example Android) apparently use a
special timezone that takes leap-seconds into account.

    */
-  int get seconds();
+  int get second();
 
   /**
-   * Returns the number of milliseconds [0...999].
+   * Returns the millisecond in the second [0...999].

[Lasse Reichstein Nielsen, 2012/06/19 14:32:18]

And again.

[floitsch, 2012/06/20 08:25:24]

Done.

    */
-  int get milliseconds();
+  int get millisecond();
 
   /**
-   * Returns the week day [MON..SUN]
+   * Returns the week day [MON..SUN]. In accordance with ISO 8601
+   * a week starts with Monday which has the value 1.
    */
   int get weekday();
 
   /**
-   * Returns milliseconds from 1970-01-01T00:00:00Z (UTC).
+   * The milliseconds since 1970-01-01T00:00:00Z (UTC). This value is
+   * independent of the time zone.
    *
-   * Note that this value is independent of the time zone.
+   * See [Stopwatch] for means to measure time-spans.
    */
-  final int value;
+  int get millisecondsSinceEpoch();
 
   /**
-   * Returns true if this [Date] is set to UTC time.
+   * True if this [Date] is set to UTC time.
    */
-  bool isUtc();
+  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.
    */
   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);
 }