Merge branch 'master' into datetimedocs

sdk/lib/core/date_time.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;
 
 /**
- * A DateTime object represents a point in time.
+ * An instant in time, such as July 20, 1969, 8:18pm.

[sethladd, 2013/08/20 19:32:49]

I'm left wondering about timezone here.

[mem, 2013/08/21 20:08:55]

Done.

  *
- * 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:].
+ * Create DateTime objects by using one of the constructors
+ * or by parsing a correctly formatted string.

[sethladd, 2013/08/20 19:32:49]

where is the definition of a correctly formatted string?

[mem, 2013/08/21 20:08:55]

Done.

+ * Note that hours are specified between 0 and 23,
+ * as in a 24-hour clock.
+ * For example:
  *
- * Also see [Stopwatch] for means to measure time-spans.
+ *     DateTime now = new DateTime.now();
+ *     DateTime berlinWallFell = new DateTime(1989, 11, 9);
+ *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");  // 8:18pm
+ *
+ * Once created, a DateTime object cannot be changed; it has no setters.

[sethladd, 2013/08/20 19:32:49]

I don't think we need "it has no setters"

[mem, 2013/08/21 20:08:55]

Done.

+ *
+ * You can use properties to get
+ * the individual units of a DateTime object.
+ *
+ *     assert(berlinWallFell.month == 11);
+ *     assert(moonLanding.hour == 20);
+ *
+ * For convenience and readability,
+ * the DateTime class provides a constant for each day and month
+ * name—for example, [AUGUST] and [FRIDAY].
+ * You can use these constants to improve code readibility:
+ *
+ *     DateTime berlinWallFell = new DateTime(1989, DateTime.NOVEMBER, 9);
+ *     assert(berlinWallFell.month == DateTime.SATURDAY);
+ *
+ * Day and month values begin at 1, and the week starts on Monday.
+ * That is, the constants [JANUARY] and [MONDAY] are both 1.
+ *
+ * ## Working with time zones
+ *
+ * The DateTime class provides support for handling time zones.

[sethladd, 2013/08/20 19:32:49]

I think this is too generous. This only creates dates in either UTC or local
time zone. "handling time zones" implies I can create a date with any time zone,
or adjust to a time zone, etc. Let's pull this back and stress this class barely
knows about time zones. And if a user was interested in time zones, have them
use the XXX class. Which I don't know what that is, so someone please tell me :)

[mem, 2013/08/21 20:08:55]

Done.

+ * One constructor allows you to create a DateTime object specified
+ * in the UTC (Universal Time Coordinated) time zone.
+ * UTC is based on the 0° longitude meridian,
+ * also known as the Greenwich meridian.
+ *
+ *     DateTime dDay = new DateTime.utc(1944, 6, 6);
+ *    
+ * Use the methods [toLocal] and [toUtc]

[sethladd, 2013/08/20 19:32:49]

I'm left wondering how DateTime knows my local timezone.

[mem, 2013/08/21 20:08:55]

Done.

+ * to convert between UTC and local time.
+ * [isUtc] indicates whether a DateTime object is based in UTC.
+ * To discover the name of the time zone use [timeZoneName].

[sethladd, 2013/08/20 19:32:49]

can we be more specific? "the time zone used when the datetime was created"

[mem, 2013/08/21 20:08:55]

Done.

+ * To find the difference
+ * between UTC and the time zone of a DateTime object
+ * call [timeZoneOffset].
+ *
+ * ## Comparing DateTime objects
+ *
+ * The DateTime class contains several handy methods,
+ * such as [isAfter], [isBefore], and [isAtSameMomentAs],
+ * for comparing DateTime objects.
+ *
+ *     assert(berlinWallFell.isAfter(moonLanding) == true);
+ *     assert(berlinWallFell.isBefore(moonLanding) == false);
+ *
+ * ## Using DateTime with Duration
+ *
+ * Use the [add] and [subtract] methods with a [Duration] object
+ * to create a new DateTime object based on another.
+ * For example, to find the date that is sixty days after today, write:
+ *
+ *     DateTime today = new DateTime.now();
+ *     DateTime sixtyDaysFromNow = today.add(new Duration(days: 60));
+ *
+ * To find out how much time is between two DateTime objects use
+ * [difference], which returns a [Duration] object:
+ *
+ *     Duration difference = berlinWallFell.difference(dDay);
+ *     assert(difference.inDays == 16592);
+ *
+ * ## Other resources
+ *
+ * See [Duration] to represent a span of time.
+ * See [Stopwatch] to measure timespans.
+ *
+ * The DateTime class does not provide internationalization.
+ * To internationalize your code, use
+ * the [intl](http://pub.dartlang.org/packages/intl) package.

[sethladd, 2013/08/20 19:32:49]

nice link!

[mem, 2013/08/21 20:08:55]

Done.

+ *
  */
 class DateTime implements Comparable {
   // Weekday constants that are returned by [weekday] method:
   static const int MONDAY = 1;
   static const int TUESDAY = 2;
   static const int WEDNESDAY = 3;
   static const int THURSDAY = 4;
   static const int FRIDAY = 5;
   static const int SATURDAY = 6;
   static const int SUNDAY = 7;
   static const int DAYS_PER_WEEK = 7;
 
   // Month constants that are returned by the [month] getter.
   static const int JANUARY = 1;
   static const int FEBRUARY = 2;
   static const int MARCH = 3;
   static const int APRIL = 4;
   static const int MAY = 5;
   static const int JUNE = 6;
   static const int JULY = 7;
   static const int AUGUST = 8;
   static const int SEPTEMBER = 9;
   static const int OCTOBER = 10;
   static const int NOVEMBER = 11;
   static const int DECEMBER = 12;
   static const int MONTHS_PER_YEAR = 12;
 
   /**
-   * The milliseconds since 1970-01-01T00:00:00Z (UTC). This value is
-   * independent of the time zone.
+   * Returns the number of milliseconds since

[Kathy Walrath, 2013/08/20 19:58:23]

Hmmm... This brings up the whole property vs. method thing.

To me, it feels like properties should have noun phrases, and that you should
mention "read-only" if necessary. (Which it might not be, since you've already
said that DateTimes are immutable, though not using that exact word.)

If you need to indicate that a field is read-only, maybe use:

The blah. (read only)
OR
The blah. [read only]
OR
Read only: The blah.
OR
[read only] The blah.

Ew. Maybe you can think of something better.

It just seems weird to use a whole different kind of phrase for a read-only
property, as opposed to a read-write property. It exposes implementation in a
slightly yucky way.

But maybe "Returns" (or better: "Gets") is the best solution. How does it read
in the docs?

PS: I just did a little research. MDN one liners don't necessarily bother
telling you that a property's read-only. An example: childElementcount in
https://developer.mozilla.org/en-US/docs/Web/API/element.

[mem, 2013/08/21 20:08:55]

The guidelines DO say that vars, getters should be noun phrases. So I fixed
those.
The signature does say 'final' so is that enough?
mem

On 2013/08/20 19:58:23, Kathy Walrath wrote:

+   * the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
    *
-   * See [Stopwatch] for means to measure time-spans.
+   * This value is independent of the time zone.
+   *
+   * This value is at most
+   * 8,640,000,000,000,000ms (100,000,000 days) from the Unix epoch.
+   * In other words: [:millisecondsSinceEpoch.abs() <= 8640000000000000:].
+   *
    */
   final int millisecondsSinceEpoch;
 
   /**
-   * True if this [DateTime] is set to UTC time.
+   * Returns true if this [DateTime] is set to UTC time.

[Kathy Walrath, 2013/08/20 19:58:23]

-> True...?

[mem, 2013/08/21 20:08:55]

Done.

+   *
+   *     DateTime dDay = new DateTime.utc(1944, 6, 6);
+   *     assert(dDay.isUtc);
+   *
    */
   final bool isUtc;
 
   /**
-   * Constructs a [DateTime] instance based on the individual parts. The date is
-   * in the local time zone.
+   * Constructs a [DateTime] instance based on the individual units.

[Kathy Walrath, 2013/08/20 19:58:23]

Maybe combine the first 2 sentences into 1:

Constructs a [DateTime] instance that uses the local time zone.

[I'm unclear. Does "local" mean the user's local time zone, at the time the code
is run? Or the DateTime is just interpreted relative to whatever the local time
zone happens to be at the time the DateTime is used?]

[mem, 2013/08/21 20:08:55]

Done.

    *
-   * [month] and [day] are one-based. For example
-   * [:new DateTime(1938, 1, 10):] represents the 10th of January 1938.
+   * The date is in the local time zone.
+   * For example,
+   * to create a new DateTime object representing April 29, 2014, 6:04am:
+   *
+   *     DateTime annularEclipse = new DateTime(2014, DateTime.APRIL, 29, 6, 4);
    */
   // TODO(8042): This should be a redirecting constructor and not a factory.
   factory DateTime(int year,
            [int month = 1,
             int day = 1,
             int hour = 0,
             int minute = 0,
             int second = 0,
             int millisecond = 0]) {
     return new DateTime._internal(
           year, month, day, hour, minute, second, millisecond, false);
   }
 
   /**
-   * Constructs a [DateTime] instance based on the individual parts. The date is
-   * in the UTC time zone.
+   * Constructs a [DateTime] instance based on the individual units.
    *
-   * [month] and [day] are one-based. For example
-   * [:new DateTime.utc(1938, 1, 10):] represents the 10th of January 1938 in
-   * Coordinated Universal Time.
+   * The date is in the UTC time zone.

[Kathy Walrath, 2013/08/20 19:58:23]

Maybe just combine the first 2 sentences into one:

Constructs a [DateTime instance] that uses the UTC time zone.

[mem, 2013/08/21 20:08:55]

Done.

+   *
+   *     DateTime dDay = new DateTime.utc(1944, DateTime.JUNE, 6);
    */
   // TODO(8042): This should be a redirecting constructor and not a factory.
   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 DateTime._internal(
           year, month, day, hour, minute, second, millisecond, true);
   }
 
   /**
-   * Constructs a new [DateTime] instance with current date time value in the
+   * Constructs a [DateTime] instance with current date and time in the
    * local time zone.
+   *
+   *     DateTime thisInstant = new DateTime.now();
+   *
    */
   // TODO(8042): This should be a redirecting constructor and not a factory.
   factory DateTime.now() { return new DateTime._now(); }
 
   /**
    * Constructs a new [DateTime] instance based on [formattedString].
    *
    * The function parses a subset of ISO 8601. Examples of accepted strings:
    *
    * * `"2012-02-27 13:27:00"`
@@ skipping 45 matching lines @@
       return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
                                                      isUtc: isUtc);
     } else {
       throw new ArgumentError(formattedString);
     }
   }
 
   static const int _MAX_MILLISECONDS_SINCE_EPOCH = 8640000000000000;
 
   /**
-   * Constructs a new [DateTime] 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 [DateTime] represents
-   * 1970-01-01T00:00:00Z + [millisecondsSinceEpoch]ms in the given
+   * 1970-01-01T00:00:00Z + [millisecondsSinceEpoch] ms in the given
    * time zone (local or UTC).
    */
   // TODO(lrn): Have two constructors instead of taking an optional bool.
   DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch,
                                       {bool isUtc: false})
       : this.millisecondsSinceEpoch = millisecondsSinceEpoch,
         this.isUtc = isUtc {
     if (millisecondsSinceEpoch.abs() > _MAX_MILLISECONDS_SINCE_EPOCH) {
       throw new ArgumentError(millisecondsSinceEpoch);
     }
     if (isUtc == null) throw new ArgumentError(isUtc);
   }
 
   /**
    * Returns true if [other] is a [DateTime] at the same moment and in the
-   * same timezone (UTC or local).
+   * same time zone (UTC or local).
    *
-   * See [isAtSameMomentAs] for a comparison that ignores the timezone.
+   *     DateTime dDayUtc   = new DateTime.utc(1944, DateTime.JUNE, 6);
+   *     DateTime dDayLocal = new DateTime(1944, DateTime.JUNE, 6);
+   *
+   *     assert(dDayUtc.isAtSameMomentAs(dDayLocal) == false);
+   *
+   * See [isAtSameMomentAs] for a comparison that adjusts for time zone.
    */
   bool operator ==(other) {
     if (!(other is DateTime)) return false;
     return (millisecondsSinceEpoch == other.millisecondsSinceEpoch &&
             isUtc == other.isUtc);
   }
 
   /**
-   * Returns true if [this] occurs before [other]. The comparison is independent
+   * Returns true if [this] occurs before [other].
+   *
+   * The comparison is independent
    * of whether the time is in UTC or in the local time zone.
+   *
+   *     DateTime berlinWallFell = new DateTime(1989, 11, 9);
+   *     DateTime moonLanding    = DateTime.parse("1969-07-20 20:18:00");
+   *
+   *     assert(berlinWallFell.isBefore(moonLanding) == false);
+   *
    */
   bool isBefore(DateTime other) {
     return millisecondsSinceEpoch < other.millisecondsSinceEpoch;
   }
 
   /**
-   * Returns true if [this] occurs after [other]. The comparison is independent
+   * Returns true if [this] occurs after [other].
+   *
+   * The comparison is independent
    * of whether the time is in UTC or in the local time zone.
+   *
+   *     DateTime berlinWallFell = new DateTime(1989, 11, 9);
+   *     DateTime moonLanding    = DateTime.parse("1969-07-20 20:18:00");
+   *
+   *     assert(berlinWallFell.isAfter(moonLanding) == true);
+   *
    */
   bool isAfter(DateTime other) {
     return millisecondsSinceEpoch > other.millisecondsSinceEpoch;
   }
 
   /**
-   * Returns true if [this] occurs at the same moment as [other]. The
-   * comparison is independent of whether the time is in UTC or in the local
+   * Returns true if [this] occurs at the same moment as [other].
+   *
+   * The comparison is independent of whether the time is in UTC or in the local
    * time zone.
+   *
+   *     DateTime berlinWallFell = new DateTime(1989, 11, 9);
+   *     DateTime moonLanding    = DateTime.parse("1969-07-20 20:18:00");
+   *
+   *     assert(berlinWallFell.isAtSameMomentAs(moonLanding) == false);
    */
   bool isAtSameMomentAs(DateTime other) {
     return millisecondsSinceEpoch == other.millisecondsSinceEpoch;
   }
 
+  /**
+   * Compares this DateTime object to [other],
+   * returning zero if the values are equal.
+   *
+   * This function returns a negative integer
+   * if this DateTime is smaller (earlier) than [other],
+   * or a positive integer if it is greater (later).

[Kathy Walrath, 2013/08/20 19:58:23]

I like the rewrite!

[mem, 2013/08/21 20:08:55]

Done.

+   */
   int compareTo(DateTime other)
       => millisecondsSinceEpoch.compareTo(other.millisecondsSinceEpoch);
 
   int get hashCode => millisecondsSinceEpoch;
 
   /**
-   * Returns [this] in the local time zone. Returns itself if it is already in
-   * the local time zone. Otherwise, this method is equivalent to
+   * Returns this DateTime value in the local time zone.
+   *
+   * Returns [this] if it is already in the local time zone,
+   * otherwise this method is equivalent to:

[Kathy Walrath, 2013/08/20 19:58:23]

, o -> . O

[mem, 2013/08/21 20:08:55]

Done.

    *
    *     new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
    *                                             isUtc: false)
    */
   DateTime toLocal() {
     if (isUtc) {
       return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
                                                      isUtc: false);
     }
     return this;
   }
 
   /**
-   * Returns [this] in UTC. Returns itself if it is already in UTC. Otherwise,
-   * this method is equivalent to
+   * Returns this DateTime value in the UTC time zone.
+   *
+   * Returns [this] if it is already in UTC,
+   * otherwise this method is equivalent to:
    *
    *     new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
    *                                             isUtc: true)
    */
   DateTime toUtc() {
     if (isUtc) return this;
     return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
                                                    isUtc: true);
   }
 
   /**
-   * Returns a human readable string for this instance.
+   * Returns a human-readable string for this instance.
+   *
    * The returned string is constructed for the time zone of this instance.
+   * The `toString()` method provides a simply formatted string.
+   * It does not support internationalized strings.
+   * Use the [intl](http://pub.dartlang.org/packages/intl) package
+   * at the pub shared packages repo.
    */
   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";
       return "${sign}000$absN";
     }
@@ skipping 16 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 [DateTime] with the [duration] added to [this]. */
+  /**
+   * Returns a new [DateTime] instance with [duration] added to [this].
+   *
+   *     DateTime today = new DateTime.now();
+   *     DateTime sixtyDaysFromNow = today.add(new Duration(days: 60));
+   */
+
   DateTime add(Duration duration) {
     int ms = millisecondsSinceEpoch;
     return new DateTime.fromMillisecondsSinceEpoch(
         ms + duration.inMilliseconds, isUtc: isUtc);
   }
 
-  /** Returns a new [DateTime] with the [duration] subtracted from [this]. */
+  /**
+   * Returns a new [DateTime] instance with [duration] subtracted from [this].
+   *
+   *     DateTime today = new DateTime.now();
+   *     DateTime sixtyDaysAgo = today.subtract(new Duration(days: 60));
+   */
   DateTime subtract(Duration duration) {
     int ms = millisecondsSinceEpoch;
     return new DateTime.fromMillisecondsSinceEpoch(
         ms - duration.inMilliseconds, isUtc: isUtc);
   }
 
-  /** Returns a [Duration] with the difference of [this] and [other]. */
+  /**
+   * Returns a [Duration] with the difference between [this] and [other].
+   *
+   *     DateTime berlinWallFell = new DateTime(1989, DateTime.NOVEMBER, 9);
+   *     DateTime dDay = new DateTime(1944, DateTime.JUNE, 6);
+   *
+   *     Duration difference = berlinWallFell.difference(dDay);
+   *     assert(difference.inDays == 16592);
+   */
+
   Duration difference(DateTime other) {
     int ms = millisecondsSinceEpoch;
     int otherMs = other.millisecondsSinceEpoch;
     return new Duration(milliseconds: ms - otherMs);
   }
 
   external DateTime._internal(int year,
                               int month,
                               int day,
                               int hour,
                               int minute,
                               int second,
                               int millisecond,
                               bool isUtc);
   external DateTime._now();
   external static int _brokenDownDateToMillisecondsSinceEpoch(
       int year, int month, int day, int hour, int minute, int second,
       int millisecond, bool isUtc);
 
   /**
-   * Returns the abbreviated time-zone name.
-   *
-   * Examples: [:"CET":] or [:"CEST":].
+   * Returns the abbreviated time zone name&mdash;for example,
+   * [:"CET":] or [:"CEST":].
    */
   external String get timeZoneName;
 
   /**
-   * The time-zone offset is the difference between local time and UTC. That is,
-   * the offset is positive for time zones west of UTC.
+   * Returns the time zone offset, which
+   * is the difference between local time and UTC.
+   *
+   * The offset is positive for time zones west of UTC.
    *
    * Note, that JavaScript, Python and C return the difference between UTC and
    * local time. Java, C# and Ruby return the difference between local time and
    * UTC.
    */
   external Duration get timeZoneOffset;
 
   /**
    * Returns the year.
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.year == 1969);
    */
   external int get year;
 
   /**
-   * Returns the month into the year [1..12].
+   * Returns the month [1..12].
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.month == 7);
+   *     assert(moonLanding.month == JULY);
    */
   external int get month;
 
   /**
-   * Returns the day into the month [1..31].
+   * Returns the day of the month [1..31].
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.day == 20);
    */
   external int get day;
 
   /**
-   * Returns the hour into the day [0..23].
+   * Returns the hour of the day [0..23].
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.hour == 20);
    */
   external int get hour;
 
   /**
-   * Returns the minute into the hour [0...59].
+   * Returns the minute [0...59].
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.minute == 18);
    */
   external int get minute;
 
   /**
-   * Returns the second into the minute [0...59].
+   * Returns the second [0...59].
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.second == 0);
    */
   external int get second;
 
   /**
-   * Returns the millisecond into the second [0...999].
+   * Returns the millisecond [0...999].
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.millisecond == 0);
    */
   external int get millisecond;
 
   /**
-   * Returns the week day [MON..SUN]. In accordance with ISO 8601
-   * a week starts with Monday which has the value 1.
+   * Returns the day of the week [MONDAY]..[SUNDAY].
+   *
+   * In accordance with ISO 8601
+   * a week starts with Monday, which has the value 1.
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.weekday == 7);
+   *     assert(moonLanding.weekday == DateTime.SUNDAY);
+   *
    */
   external int get weekday;
 }