Deprecate use of timezones.

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.
  */
 interface Date extends Comparable, Hashable default DateImplementation {
@@ skipping 15 matching lines @@
   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.
+   * 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,
         int day,
         int hours,
         int minutes,
         int seconds,
-        int milliseconds]);
+        int milliseconds,
+        bool isUtc]);
 
   /**
    * Constructs a [Date] instance based on the individual parts.
    * [timeZone] may not be [:null:].
+   *
+   * *DEPRECATED*
    */
   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.
    */
   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:].
-   *
-   * This constructor is the only one that doesn't need to be computations and
-   * which can therefore be [:const:].
+   * Constructs a new [Date] instance with the given [value]. 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 [timeZone].

[ngeoffray, 2012/05/22 08:58:45]

Update comment

[floitsch, 2012/05/22 14:50:38]

Done.

    */
-  const Date.fromEpoch(int value, TimeZone timeZone);
+  Date.fromEpoch(int value, [bool isUtc]);
 
   /**
+   * Returns true if [this] occurs at the same time as [other]. The
+   * comparison is independent of the time zone the [Date] is in.

[ngeoffray, 2012/05/22 08:58:45]

of whether the time is utc or in the local time zone.

[floitsch, 2012/05/22 14:50:38]

Done.

+   */
+  bool operator ==(Date other);
+  /**
    * Returns true if [this] occurs before [other]. The comparison is independent
-   * of the timezone the [Date] is in.
+   * of the time zone the [Date] is in.
    */
   bool operator <(Date other);
   /**
    * Returns true if [this] occurs at the same time or before [other]. The
-   * comparison is independent of the timezone the [Date] is in.
+   * comparison is independent of the time zone the [Date] is in.
    */
   bool operator <=(Date other);
   /**
    * Returns true if [this] occurs after [other]. The comparison is independent
-   * of the timezone the [Date] is in.
+   * of the time zone the [Date] is in.
    */
   bool operator >(Date other);
   /**
    * Returns true if [this] occurs at the same time or after [other]. The
-   * comparison is independent of the timezone the [Date] is in.
+   * comparison is independent of the time zone the [Date] is in.
    */
   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 equvalent to

[ngeoffray, 2012/05/22 08:58:45]

equivalent

[floitsch, 2012/05/22 14:50:38]

Done.

+   * [:new Date.fromEpoch(this.value, isUtc: false):].
+   */
+  Date toLocal();
+
+  /**
+   * Returns [this] in UTC. Returns itself it is already in UTC. Otherwise, this

[ngeoffray, 2012/05/22 08:58:45]

itself *if* it is

[floitsch, 2012/05/22 14:50:38]

Done.

+   * method is equvalent to [:new Date.fromEpoch(this.value, isUtc: true):].

[ngeoffray, 2012/05/22 08:58:45]

equivalent

[floitsch, 2012/05/22 14:50:38]

Done.

+   */
+  Date toUtc();
+
   /**
    * 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):].
+   *
+   * *DEPRECATED*
    */
   Date changeTimeZone(TimeZone targetTimeZone);
 
   /**
    * Returns the abbreviated time-zone name.
    *
    * Examples: [:"CET":] or [:"CEST":].
    */
   String get timeZoneName();
 
@@ skipping 49 matching lines @@
 
   /**
    * Returns milliseconds from 1970-01-01T00:00:00Z (UTC).
    *
    * Note that this value is independent of [timeZone].
    */
   final int value;
 
   /**
    * Returns the timeZone of this instance.
+   *
+   * *DEPRECATED*.
    */
   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.
    */
   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);
 }