description

# Duration class

A difference between points in time.

A `Duration` is a signed number of microseconds, which represents an offset from a point in time to another. You can add a `Duration` to a DateTime, which gives the point in time that is offset by that duration from the original.

Most durations are positive and represent an offset to a later time. A positive duration is useful for representing a delay, a point in the future relative to now (as used by Future.delayed), or as a measure of time that has passed from an earlier time until now (as reported by Stopwatch.elapsed).

A negative duration is the difference from a later time to an earlier, and adding it to a time gives an earlier time. You cannot wait for a negative amount of time using Future.delayed.

Durations are independent of calendars. For example, a duration of 2 days is always 48 hours, even when it is added to a `DateTime` just when the time zone is about to make a daylight-savings switch. (See DateTime.add).

A duration is a (positive or negative) number of microseconds. Durations are ordered by this number of microseconds when compared using operator < or compareTo.

Despite the same name, a `Duration` object does not implement "Durations" as specified by ISO 8601. In particular, a duration object does not keep track of the individually provided members (such as "days" or "hours"), but only uses these arguments to compute the length of the corresponding time interval.

To create a new `Duration` object, use this class's single constructor giving the appropriate arguments:

    const fastestMarathon = Duration(hours: 2, minutes: 3, seconds: 2);

The created Duration is defined by the number of microseconds that is the sum of all the individual arguments to the constructor.

Properties can access that single number in different ways. The inMicroseconds is the entire value, and, for example, inMinutes gives the number of whole minutes in the total duration, which includes any minutes that were provided as "hours" to the constructor or provided as "seconds" with a value of 60 or above.

    const fastestMarathon = Duration(hours: 2, minutes: 0, seconds: 35);
    print(fastestMarathon.inDays); // 0
    print(fastestMarathon.inHours); // 2
    print(fastestMarathon.inMinutes); // 120
    print(fastestMarathon.inSeconds); // 7235
    print(fastestMarathon.inMilliseconds); // 7235000

If a duration is negative, all the properties derived from the duration are non-positive (negative unless they are zero).

    const overDayAgo = Duration(days: -1, hours: -10);
    print(overDayAgo.inDays); // -1
    print(overDayAgo.inHours); // -34
    print(overDayAgo.inMinutes); // -2040

Use one of the properties, such as inDays, to retrieve the integer value of the `Duration` in the specified time unit. Note that the returned value is rounded towards zero. For example,

    const aLongWeekend = Duration(hours: 88);
    print(aLongWeekend.inDays); // 3
    const aLongWeekendAgo = Duration(hours: -88);
    print(aLongWeekendAgo.inDays); // -3

A duration also provides arithmetic and comparison operators, all based on the microsecond offset of the duration. and the class provides a set of constants useful for converting between time units.

    const firstHalf = Duration(minutes: 45); // 00:45:00.000000
    const secondHalf = Duration(minutes: 45); // 00:45:00.000000
    const overTime = Duration(minutes: 30); // 00:30:00.000000
    final maxGameTime = firstHalf + secondHalf + overTime;
    print(maxGameTime.inMinutes); // 120

    // The duration of the firstHalf and secondHalf is the same, returns 0.
    var result = firstHalf.compareTo(secondHalf);
    print(result); // 0

    // Duration of overTime is shorter than firstHalf, returns < 0.
    result = overTime.compareTo(firstHalf);
    print(result); // < 0

    // Duration of secondHalf is longer than overTime, returns > 0.
    result = secondHalf.compareTo(overTime);
    print(result); // > 0

See also:

- DateTime to represent a point in time.
- Stopwatch to measure time-spans.

Implemented types
  - Comparable<Duration>

## Constructors

Duration({int days = 0, int hours = 0, int minutes = 0, int seconds = 0, int milliseconds = 0, int microseconds = 0})
  Creates a new Duration object whose value is the sum of all individual parts.
  const

## Properties

hashCode → int
  The hash code of a duration is the hash code of its inMicroseconds.
  no setter override
inDays → int
  The number of entire days spanned by this Duration.
  no setter
inHours → int
  The number of entire hours spanned by this Duration.
  no setter
inMicroseconds → int
  The time offset of this duration in microseconds.
  final
inMilliseconds → int
  The number of whole milliseconds spanned by this Duration.
  no setter
inMinutes → int
  The number of whole minutes spanned by this Duration.
  no setter
inSeconds → int
  The number of whole seconds spanned by this Duration.
  no setter
isNegative → bool
  Whether this Duration is negative.
  no setter
runtimeType → Type
  A representation of the runtime type of the object.
  no setter inherited

## Methods

abs() → Duration
  A positive Duration with the same absolute length as this Duration.
compareTo(Duration other) → int
  Compares this Duration to `other`.
  override
noSuchMethod(Invocation invocation) → dynamic
  Invoked when a nonexistent method or property is accessed.
  inherited
toString() → String
  A string representation of this Duration.
  override

## Operators

operator *(num factor) → Duration
  This Duration scaled by `factor`.
operator +(Duration other) → Duration
  Adds this `Duration` and `other` and returns the sum as a new `Duration` object.
operator -(Duration other) → Duration
  The offset of this duration minus the offset of `other`.
operator <(Duration other) → bool
  Whether this duration's offset is smaller than that of `other`.
operator <=(Duration other) → bool
  Whether this duration's offset is not greater than that of `other`.
operator ==(Object other) → bool
  Whether this Duration is equivalent to `other`.
  override
operator >(Duration other) → bool
  Whether this duration's offset is greater than that of `other`.
operator >=(Duration other) → bool
  Whether this duration's offset is not smaller than that of `other`.
operator unary-() → Duration
  Creates a new Duration with the opposite sign of this Duration.
operator ~/(int quotient) → Duration
  One-`quotient`th of this duration.

## Constants

hoursPerDay → const int
  The number of hours per day.
microsecondsPerDay → const int
  The number of microseconds per day.
microsecondsPerHour → const int
  The number of microseconds per hour.
microsecondsPerMillisecond → const int
  The number of microseconds per millisecond.
microsecondsPerMinute → const int
  The number of microseconds per minute.
microsecondsPerSecond → const int
  The number of microseconds per second.
millisecondsPerDay → const int
  The number of milliseconds per day.
millisecondsPerHour → const int
  The number of milliseconds per hour.
millisecondsPerMinute → const int
  The number of milliseconds per minute.
millisecondsPerSecond → const int
  The number of milliseconds per second.
minutesPerDay → const int
  The number of minutes per day.
minutesPerHour → const int
  The number of minutes per hour.
secondsPerDay → const int
  The number of seconds per day.
secondsPerHour → const int
  The number of seconds per hour.
secondsPerMinute → const int
  The number of seconds per minute.
zero → const Duration
  An empty duration, representing zero time.