Reapply "Refactor Date implementation in VM."

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:].
  */
 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. The date is
-   * in the local time-zone if [isUtc] is false.
+   * 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,
         int day,
         int hours,
         int minutes,
         int seconds,
         int milliseconds,
         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.
+   * 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 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]);
 
   /**
    * 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.
    */
@@ skipping 16 matching lines @@
   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);
 
 
   /**
-   * Returns [this] in the local time-zone. Returns itself if it is already in
+   * 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):].
    */
   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):].
    */
@@ skipping 82 matching lines @@
   /**
    * 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);
 }