Adding Duration documentation, abs(), and isNegative()

sdk/lib/core/duration.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 span of time, such as 27 days, 4 hours, 12 minutes, and 3 seconds.
  *
+ * A `Duration` represents a difference from one point in time to another. The
+ * duration may be "negative" if the difference is from a later time to an
+ * earlier.
+ *
  * To create a new Duration object, use this class's single constructor
  * giving the appropriate arguments:
  *
  *     Duration fastestMarathon = new Duration(hours:2, minutes:3, seconds:2);
  *
  * The Duration is the sum of all individual parts.
  * This means that individual parts can be larger than the next-bigger unit.
  * For example, [minutes] can be greater than 59.
  *
  *     assert(fastestMarathon.inMinutes == 123);
@@ skipping 181 matching lines @@
    * Returns `true` if this Duration is the same object as [other].
    */
   bool operator ==(other) {
     if (other is !Duration) return false;
     return _duration == other._duration;
   }
 
   int get hashCode => _duration.hashCode;
 
   /**
-   * Compares this Duration to [other],
-   * returning zero if the values are equal.
+   * Compares this Duration to [other], returning zero if the values are equal.
    *
-   * This function returns a negative integer
-   * if this Duration is smaller than [other],
-   * or a positive integer if it is greater.
+   * Returns a negative integer if this `Duration` is shorter than
+   * [other], or a positive integer if it is longer.
+   *
+   * A negative `Duration` is always considered shorter than a positive one.
+   *
+   * It is always the case that `duration1.compareTo(duration2) < 0` iff
+   * `(someDate + duration1).compareTo(someDate + duration2) < 0`.
    */
   int compareTo(Duration other) => _duration.compareTo(other._duration);
 
+  /**
+   * Returns a string representation of this `Duration`.
+   *
+   * Returns a string with hours, minutes, seconds, and microseconds, in the
+   * following format: `HH:MM:SS.mmmmmm`. For example,
+   *
+   *     var d = new Duration(days:1, hours:1, minutes:33, microseconds: 500);
+   *     d.toString();  // "25:33:00.000500"
+   */
   String toString() {
     String sixDigits(int n) {
       if (n >= 100000) return "$n";
       if (n >= 10000) return "0$n";
       if (n >= 1000) return "00$n";
       if (n >= 100) return "000$n";
       if (n >= 10) return "0000$n";
       return "00000$n";
     }
     String twoDigits(int n) {
       if (n >= 10) return "$n";
       return "0$n";
     }
 
     if (inMicroseconds < 0) {
       Duration duration =
           new Duration(microseconds: -inMicroseconds);
       return "-$duration";
     }
     String twoDigitMinutes = twoDigits(inMinutes.remainder(MINUTES_PER_HOUR));
     String twoDigitSeconds = twoDigits(inSeconds.remainder(SECONDS_PER_MINUTE));
     String sixDigitUs =
         sixDigits(inMicroseconds.remainder(MICROSECONDS_PER_SECOND));
     return "$inHours:$twoDigitMinutes:$twoDigitSeconds.$sixDigitUs";
   }
+
+  /**
+   * Returns whether this `Duration` is negative.
+   *
+   * A negative `Duration` represents the difference from a later time to an
+   * earlier time.
+   */
+  bool get isNegative => _duration < 0;
+
+  /**
+   * Returns a new `Duration` representing the absolute value of this
+   * `Duration`.
+   *
+   * The returned `Duration` has the same length as this one, but is always
+   * positive.
+   */
+  Duration abs() => new Duration(microseconds: _duration.abs());
+
+  /**
+   * Returns a new `Duration` representing this `Duration` negated.
+   *
+   * The returned `Duration` has the same length as this one, but will have the
+   * opposite sign of this one.
+   */
+  Duration operator -() => new Duration(microseconds: -_duration);
 }