Add microsecond support to DateTime.

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;
 
 /**
  * An instant in time, such as July 20, 1969, 8:18pm GMT.
  *
  * Create a DateTime object by using one of the constructors
@@ skipping 111 matching lines @@
   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 number of milliseconds since
-   * the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
+   * The value of this DateTime.
    *
-   * 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:].
-   *
+   * The content of this field is implementation dependent. On JavaScript it is
+   * equal to [millisecondsSinceEpoch]. On the VM it is equal to
+   * [microsecondsSinceEpoch].
    */
-  final int millisecondsSinceEpoch;
+  final int _value;
 
   /**
    * True if this [DateTime] is set to UTC time.
    *
    *     DateTime dDay = new DateTime.utc(1944, 6, 6);
    *     assert(dDay.isUtc);
    *
    */
   final bool isUtc;
 
   /**
    * Constructs a [DateTime] instance specified 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);
    */
   DateTime(int year,
            [int month = 1,
             int day = 1,
             int hour = 0,
             int minute = 0,
             int second = 0,
-            int millisecond = 0])
+            int millisecond = 0,
+            int microsecond = 0])
       : this._internal(
-            year, month, day, hour, minute, second, millisecond, false);
+            year, month, day, hour, minute, second, millisecond, microsecond,
+            false);
 
   /**
    * Constructs a [DateTime] instance specified in the UTC time zone.
    *
    *     DateTime dDay = new DateTime.utc(1944, DateTime.JUNE, 6);
    */
   DateTime.utc(int year,
                [int month = 1,
                 int day = 1,
                 int hour = 0,
                 int minute = 0,
                 int second = 0,
-                int millisecond = 0])
+                int millisecond = 0,
+                int microsecond = 0])
     : this._internal(
-          year, month, day, hour, minute, second, millisecond, true);
+          year, month, day, hour, minute, second, millisecond, microsecond,
+          true);
 
   /**
    * Constructs a [DateTime] instance with current date and time in the
    * local time zone.
    *
    *     DateTime thisInstant = new DateTime.now();
    *
    */
   DateTime.now() : this._now();
 
@@ skipping 54 matching lines @@
      * yeardate ::= year colon_opt month colon_opt day
      * year ::= sign_opt digit{4,6}
      * colon_opt :: <empty> | ':'
      * sign ::= '+' | '-'
      * sign_opt ::=  <empty> | sign
      * month ::= digit{2}
      * day ::= digit{2}
      * time_opt ::= <empty> | (' ' | 'T') hour minutes_opt
      * minutes_opt ::= <empty> | colon_opt digit{2} seconds_opt
      * seconds_opt ::= <empty> | colon_opt digit{2} millis_opt
-     * millis_opt ::= <empty> | '.' digit{1,6}
+     * micros_opt ::= <empty> | '.' digit{1,6}
      * timezone_opt ::= <empty> | space_opt timezone
      * space_opt :: ' ' | <empty>
      * timezone ::= 'z' | 'Z' | sign digit{2} timezonemins_opt
      * timezonemins_opt ::= <empty> | colon_opt digit{2}
      */
     final RegExp re = new RegExp(
         r'^([+-]?\d{4,6})-?(\d\d)-?(\d\d)'  // Day part.
         r'(?:[ T](\d\d)(?::?(\d\d)(?::?(\d\d)(?:\.(\d{1,6}))?)?)?' // Time part.
         r'( ?[zZ]| ?([-+])(\d\d)(?::?(\d\d))?)?)?$'); // Timezone part.
 
     Match match = re.firstMatch(formattedString);
     if (match != null) {
       int parseIntOrZero(String matched) {
         if (matched == null) return 0;
         return int.parse(matched);
       }
 
-      // Parses fractional second digits of '.(\d{1,6})' into milliseconds.
-      // Uses first three digits (assumed to be zero if not there), and
-      // rounds up if fourth digit is 5 or greater.
-      // Should be equivalent to `(double.parse(".$matchd")*1000).round()`.
-      int parseMilliseconds(String matched) {
+      // Parses fractional second digits of '.(\d{1,6})' into the combined
+      // microseconds.
+      int parseMilliAndMicroseconds(String matched) {
         if (matched == null) return 0;
         int length = matched.length;
         assert(length >= 1);
         assert(length <= 6);
 
-        int result = (matched.codeUnitAt(0) ^ 0x30);
-        if (length <= 3) {
-          int i = 1;
-          while (i < length) {
-            result *= 10;
+        int result = 0;
+        for (int i = 0; i < 6; i++) {
+          result *= 10;
+          if (i < matched.length) {
             result += matched.codeUnitAt(i) ^ 0x30;
-            i++;
           }
-          while (i < 3) {
-            result *= 10;
-            i++;
-          }
-          return result;
-        }
-        // Parse the prefix from 0..3 without creating a new substring.
-        result = result * 10 + (matched.codeUnitAt(1) ^ 0x30);
-        result = result * 10 + (matched.codeUnitAt(2) ^ 0x30);
-        if (matched.codeUnitAt(3) >= 0x35) {
-          result += 1;
         }
         return result;
       }
 
       int years = int.parse(match[1]);
       int month = int.parse(match[2]);
       int day = int.parse(match[3]);
       int hour = parseIntOrZero(match[4]);
       int minute = parseIntOrZero(match[5]);
       int second = parseIntOrZero(match[6]);
       bool addOneMillisecond = false;
-      int millisecond = parseMilliseconds(match[7]);
-      if (millisecond == 1000) {
-        addOneMillisecond = true;
-        millisecond = 999;
-      }
+      int milliAndMicroseconds = parseMilliAndMicroseconds(match[7]);
+      int millisecond =
+          milliAndMicroseconds ~/ Duration.MICROSECONDS_PER_MILLISECOND;
+      int microsecond =
+          milliAndMicroseconds.remainder(Duration.MICROSECONDS_PER_MILLISECOND);
       bool isUtc = false;
       if (match[8] != null) {  // timezone part
         isUtc = true;
         if (match[9] != null) {
           // timezone other than 'Z' and 'z'.
           int sign = (match[9] == '-') ? -1 : 1;
           int hourDifference = int.parse(match[10]);
           int minuteDifference = parseIntOrZero(match[11]);
           minuteDifference += 60 * hourDifference;
           minute -= sign * minuteDifference;
         }
       }
-      int millisecondsSinceEpoch = _brokenDownDateToMillisecondsSinceEpoch(
-          years, month, day, hour, minute, second, millisecond, isUtc);
-      if (millisecondsSinceEpoch == null) {
+      int value = _brokenDownDateToValue(
+          years, month, day, hour, minute, second, millisecond, microsecond,
+          isUtc);
+      if (value == null) {
         throw new FormatException("Time out of range", formattedString);
       }
-      if (addOneMillisecond) millisecondsSinceEpoch++;
-      return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
-                                                     isUtc: isUtc);
+      return new DateTime._withValue(value, isUtc: isUtc);
     } else {
       throw new FormatException("Invalid date format", formattedString);
     }
   }
 
   static const int _MAX_MILLISECONDS_SINCE_EPOCH = 8640000000000000;
 
   /**
    * 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
    * time zone (local or UTC).
    */
-  DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch,
-                                      {bool isUtc: false})
-      : this.millisecondsSinceEpoch = millisecondsSinceEpoch,
-        this.isUtc = isUtc {
-    if (millisecondsSinceEpoch.abs() > _MAX_MILLISECONDS_SINCE_EPOCH) {
+  external DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch,
+                                              {bool isUtc: false});
+
+  /**
+   * Constructs a new [DateTime] instance
+   * with the given [microsecondsSinceEpoch].
+   *
+   * If [isUtc] is false then the date is in the local time zone.
+   *
+   * The constructed [DateTime] represents
+   * 1970-01-01T00:00:00Z + [microsecondsSinceEpoch] us in the given
+   * time zone (local or UTC).
+   */
+  external DateTime.fromMicrosecondsSinceEpoch(int microsecondsSinceEpoch,
+                                               {bool isUtc: false});
+
+  /**
+   * Constructs a new [DateTime] instance with the given value.
+   *
+   * If [isUtc] is false then the date is in the local time zone.
+   */
+  DateTime._withValue(this._value, {this.isUtc}) {
+    if (millisecondsSinceEpoch.abs() > _MAX_MILLISECONDS_SINCE_EPOCH ||
+        (millisecondsSinceEpoch.abs() == _MAX_MILLISECONDS_SINCE_EPOCH &&
+         microsecond != 0)) {
       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 time zone (UTC or local).
    *
    *     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);
+    return (_value == other._value && isUtc == other.isUtc);
   }
 
   /**
    * 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;
+    return _value < other._value;
   }
 
   /**
    * 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;
+    return _value > other._value;
   }
 
   /**
    * 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;
+    return _value == other._value;
   }
 
   /**
    * 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).
    */
-  int compareTo(DateTime other)
-      => millisecondsSinceEpoch.compareTo(other.millisecondsSinceEpoch);
+  int compareTo(DateTime other) => _value.compareTo(other._value);
 
-  int get hashCode => millisecondsSinceEpoch;
+  int get hashCode => (_value ^ (_value >> 30)) & 0x3FFFFFFF;
 
   /**
    * 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:
    *
-   *     new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
+   *     new DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch,
    *                                             isUtc: false)
    */
   DateTime toLocal() {
     if (isUtc) {
-      return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
-                                                     isUtc: false);
+      return new DateTime._withValue(_value, isUtc: false);
     }
     return this;
   }
 
   /**
    * 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,
+   *     new DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch,
    *                                             isUtc: true)
    */
   DateTime toUtc() {
     if (isUtc) return this;
-    return new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
-                                                   isUtc: true);
+    return new DateTime._withValue(_value, isUtc: true);
   }
 
   static 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 29 matching lines @@
    * The resulting string can be parsed back using [parse].
    */
   String toString() {
     String y = _fourDigits(year);
     String m = _twoDigits(month);
     String d = _twoDigits(day);
     String h = _twoDigits(hour);
     String min = _twoDigits(minute);
     String sec = _twoDigits(second);
     String ms = _threeDigits(millisecond);
+    String us = microsecond == 0 ? "" : _threeDigits(microsecond);
     if (isUtc) {
-      return "$y-$m-$d $h:$min:$sec.${ms}Z";
+      return "$y-$m-$d $h:$min:$sec.$ms${us}Z";
     } else {
-      return "$y-$m-$d $h:$min:$sec.$ms";
+      return "$y-$m-$d $h:$min:$sec.$ms$us";
     }
   }
 
   /**
    * Returns an ISO-8601 full-precision extended format representation.
    *
-   * The format is `yyyy-MM-ddTHH:mm:ss.sssZ` for UTC time, and
-   * `yyyy-MM-ddTHH:mm:ss.sss` (no trailing "Z") for local/non-UTC time,
+   * The format is `yyyy-MM-ddTHH:mm:ss.mmmuuuZ` for UTC time, and
+   * `yyyy-MM-ddTHH:mm:ss.mmmuuu` (no trailing "Z") for local/non-UTC time,
    * where:
    *
    * * `yyyy` is a, possibly negative, four digit representation of the year,
    *   if the year is in the range -9999 to 9999,
    *   otherwise it is a signed six digit representation of the year.
    * * `MM` is the month in the range 01 to 12,
    * * `dd` is the day of the month in the range 01 to 31,
    * * `HH` are hours in the range 00 to 23,
    * * `mm` are minutes in the range 00 to 59,
-   * * `ss` are seconds in the range 00 to 59 (no leap seconds), and
-   * * `sss` are milliseconds in the range 000 to 999.
+   * * `ss` are seconds in the range 00 to 59 (no leap seconds),
+   * * `mmm` are microseconds in the range 000 to 999, and
+   * * `uuu` are microseconds in the range 001 to 999. If [microsecond] equals
+   *   0, then this part is omitted.
    *
    * The resulting string can be parsed back using [parse].
    */
   String toIso8601String() {
     String y = (year >= -9999 && year <= 9999) ? _fourDigits(year)
                                                : _sixDigits(year);
     String m = _twoDigits(month);
     String d = _twoDigits(day);
     String h = _twoDigits(hour);
     String min = _twoDigits(minute);
     String sec = _twoDigits(second);
     String ms = _threeDigits(millisecond);
+    String us = microsecond == 0 ? "" : _threeDigits(microsecond);
     if (isUtc) {
-      return "$y-$m-${d}T$h:$min:$sec.${ms}Z";
+      return "$y-$m-${d}T$h:$min:$sec.$ms${us}Z";
     } else {
-      return "$y-$m-${d}T$h:$min:$sec.$ms";
+      return "$y-$m-${d}T$h:$min:$sec.$ms$us";
     }
   }
 
   /**
    * 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);
-  }
+  external DateTime add(Duration duration);
 
   /**
    * 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);
-  }
+  external DateTime subtract(Duration duration);
 
   /**
    * 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 Duration difference(DateTime other);
 
   external DateTime._internal(int year,
                               int month,
                               int day,
                               int hour,
                               int minute,
                               int second,
                               int millisecond,
+                              int microsecond,
                               bool isUtc);
+
   external DateTime._now();
-  /// Returns the time as milliseconds since epoch, or null if the
-  /// values are out of range.
-  external static int _brokenDownDateToMillisecondsSinceEpoch(
+
+  /// Returns the time as value (millisecond or microsecond since epoch), or
+  /// null if the values are out of range.
+  external static int _brokenDownDateToValue(
       int year, int month, int day, int hour, int minute, int second,
-      int millisecond, bool isUtc);
+      int millisecond, int microsecond, bool isUtc);
+
+  /**
+   * The number of milliseconds since
+   * the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
+   *
+   * 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`.
+   */
+  external int get millisecondsSinceEpoch;
+
+  /**
+   * The number of microseconds since
+   * the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
+   *
+   * This value is independent of the time zone.
+   *
+   * This value is at most
+   * 8,640,000,000,000,000,000us (100,000,000 days) from the Unix epoch.
+   * In other words: `microsecondsSinceEpoch.abs() <= 8640000000000000000`.
+   *
+   * Note that this value does not fit into 53 bits (the size of a IEEE double).
+   * A JavaScript number is not able to hold this value.
+   */
+  external int get microsecondsSinceEpoch;
 
   /**
    * The abbreviated time zone name&mdash;for example,
    * [:"CET":] or [:"CEST":].
    */
   external String get timeZoneName;
 
   /**
    * The time zone offset, which
    * is the difference between local time and UTC.
@@ skipping 57 matching lines @@
 
   /**
    * The millisecond [0...999].
    *
    *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
    *     assert(moonLanding.millisecond == 0);
    */
   external int get millisecond;
 
   /**
+   * The microsecond [0...999].
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.microsecond == 0);
+   */
+  external int get microsecond;
+
+  /**
    * 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;
 }