Duration

class Duration implements Comparable<Duration>

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.

Durations are context independent. 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).

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 Duration represents a single number of microseconds, which is the sum of all the individual arguments to the constructor.

Properties can access that single number in different ways. For example the inMinutes gives the number of whole minutes in the total duration, which includes the minutes that were provided as "hours" to the constructor, and can be larger than 59.

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

The duration can be negative, in which case all the properties derived from the duration are also non-positive.

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 down. For example,

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

This class provides a collection of arithmetic and comparison operators, plus a set of constants useful for converting 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<T>

Constructors

Duration() const

const 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.

Individual parts can be larger than the number of those parts in the next larger unit. For example, hours can be greater than 23. If this happens, the value overflows into the next larger unit, so 26 hours is the same as 2 hours and one more days. Likewise, values can be negative, in which case they underflow and subtract from the next larger unit.

If the total number of microseconds cannot be represented as an integer value, the number of microseconds might overflow and be truncated to a smaller number of bits, or it might lose precision.

All arguments are 0 by default.

const duration = Duration(days: 1, hours: 8, minutes: 56, seconds: 59,
  milliseconds: 30, microseconds: 10);
print(duration); // 32:56:59.030010

Implementation

const Duration({
  int days = 0,
  int hours = 0,
  int minutes = 0,
  int seconds = 0,
  int milliseconds = 0,
  int microseconds = 0,
}) : this._microseconds(
       microseconds +
           microsecondsPerMillisecond * milliseconds +
           microsecondsPerSecond * seconds +
           microsecondsPerMinute * minutes +
           microsecondsPerHour * hours +
           microsecondsPerDay * days,
     );

Properties

hashCode no setter override

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Implementation

int get hashCode => _duration.hashCode;

inDays no setter

int get inDays

The number of entire days spanned by this Duration.

For example, a duration of four days and three hours has four entire days.

const duration = Duration(days: 4, hours: 3);
print(duration.inDays); // 4

Implementation

int get inDays => _duration ~/ Duration.microsecondsPerDay;

inHours no setter

int get inHours

The number of entire hours spanned by this Duration.

The returned value can be greater than 23. For example, a duration of four days and three hours has 99 entire hours.

const duration = Duration(days: 4, hours: 3);
print(duration.inHours); // 99

Implementation

int get inHours => _duration ~/ Duration.microsecondsPerHour;

inMicroseconds no setter

int get inMicroseconds

The number of whole microseconds spanned by this Duration.

The returned value can be greater than 999999. For example, a duration of three seconds, 125 milliseconds and 369 microseconds has 3125369 microseconds.

const duration = Duration(seconds: 3, milliseconds: 125,
    microseconds: 369);
print(duration.inMicroseconds); // 3125369

Implementation

int get inMicroseconds => _duration;

inMilliseconds no setter

int get inMilliseconds

The number of whole milliseconds spanned by this Duration.

The returned value can be greater than 999. For example, a duration of three seconds and 125 milliseconds has 3125 milliseconds.

const duration = Duration(seconds: 3, milliseconds: 125);
print(duration.inMilliseconds); // 3125

Implementation

int get inMilliseconds => _duration ~/ Duration.microsecondsPerMillisecond;

inMinutes no setter

int get inMinutes

The number of whole minutes spanned by this Duration.

The returned value can be greater than 59. For example, a duration of three hours and 12 minutes has 192 minutes.

const duration = Duration(hours: 3, minutes: 12);
print(duration.inMinutes); // 192

Implementation

int get inMinutes => _duration ~/ Duration.microsecondsPerMinute;

inSeconds no setter

int get inSeconds

The number of whole seconds spanned by this Duration.

The returned value can be greater than 59. For example, a duration of three minutes and 12 seconds has 192 seconds.

const duration = Duration(minutes: 3, seconds: 12);
print(duration.inSeconds); // 192

Implementation

int get inSeconds => _duration ~/ Duration.microsecondsPerSecond;

isNegative no setter

bool get isNegative

Whether this Duration is negative.

A negative Duration represents the difference from a later time to an earlier time.

Implementation

bool get isNegative => _duration < 0;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Methods

abs()

Duration abs()

Creates a new Duration representing the absolute length of this Duration.

The returned Duration has the same length as this one, but is always positive where possible.

Implementation

Duration abs() => Duration._microseconds(_duration.abs());

compareTo() override

int compareTo(Duration other)

Compares this Duration to other, returning zero if the values are equal.

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.

Implementation

int compareTo(Duration other) => _duration.compareTo(other._duration);

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

toString() override

String toString()

Returns a string representation of this Duration.

Returns a string with hours, minutes, seconds, and microseconds, in the following format: H:MM:SS.mmmmmm. For example,

var d = const Duration(days: 1, hours: 1, minutes: 33, microseconds: 500);
print(d.toString()); // 25:33:00.000500

d = const Duration(hours: 1, minutes: 10, microseconds: 500);
print(d.toString()); // 1:10:00.000500

Implementation

String toString() {
  var microseconds = inMicroseconds;
  var sign = "";
  var negative = microseconds < 0;

  var hours = microseconds ~&#47; microsecondsPerHour;
  microseconds = microseconds.remainder(microsecondsPerHour);

  &#47;&#47; Correcting for being negative after first division, instead of before,
  &#47;&#47; to avoid negating min-int, -(2^31-1), of a native int64.
  if (negative) {
    hours = 0 - hours; &#47;&#47; Not using `-hours` to avoid creating -0.0 on web.
    microseconds = 0 - microseconds;
    sign = "-";
  }

  var minutes = microseconds ~&#47; microsecondsPerMinute;
  microseconds = microseconds.remainder(microsecondsPerMinute);

  var minutesPadding = minutes < 10 ? "0" : "";

  var seconds = microseconds ~&#47; microsecondsPerSecond;
  microseconds = microseconds.remainder(microsecondsPerSecond);

  var secondsPadding = seconds < 10 ? "0" : "";

  &#47;&#47; Padding up to six digits for microseconds.
  var microsecondsText = microseconds.toString().padLeft(6, "0");

  return "$sign$hours:"
      "$minutesPadding$minutes:"
      "$secondsPadding$seconds."
      "$microsecondsText";
}

Operators

operator *()

Duration operator *(num factor)

Multiplies this Duration by the given factor and returns the result as a new Duration object.

Note that when factor is a double, and the duration is greater than 53 bits, precision is lost because of double-precision arithmetic.

Implementation

Duration operator *(num factor) {
  return Duration._microseconds((_duration * factor).round());
}

operator +()

Duration operator +(Duration other)

Adds this Duration and other and returns the sum as a new Duration object.

Implementation

Duration operator +(Duration other) {
  return Duration._microseconds(_duration + other._duration);
}

operator -()

Duration operator -(Duration other)

Subtracts other from this Duration and returns the difference as a new Duration object.

Implementation

Duration operator -(Duration other) {
  return Duration._microseconds(_duration - other._duration);
}

operator <()

bool operator <(Duration other)

Whether this Duration is shorter than other.

Implementation

bool operator <(Duration other) => this._duration < other._duration;

operator <=()

bool operator <=(Duration other)

Whether this Duration is shorter than or equal to other.

Implementation

bool operator <=(Duration other) => this._duration <= other._duration;

operator ==() override

bool operator ==(Object other)

Whether this Duration has the same length as other.

Durations have the same length if they have the same number of microseconds, as reported by inMicroseconds.

Implementation

bool operator ==(Object other) =>
    other is Duration && _duration == other.inMicroseconds;

operator >()

bool operator >(Duration other)

Whether this Duration is longer than other.

Implementation

bool operator >(Duration other) => this._duration > other._duration;

operator >=()

bool operator >=(Duration other)

Whether this Duration is longer than or equal to other.

Implementation

bool operator >=(Duration other) => this._duration >= other._duration;

operator unary-()

Duration operator unary-()

Creates a new Duration with the opposite direction of this Duration.

The returned Duration has the same length as this one, but will have the opposite sign (as reported by isNegative) as this one where possible.

Implementation

// Using subtraction helps dart2js avoid negative zeros.
Duration operator -() => Duration._microseconds(0 - _duration);

operator ~/()

Duration operator ~/(int quotient)

Divides this Duration by the given quotient and returns the truncated result as a new Duration object.

The quotient must not be 0.

Implementation

Duration operator ~/(int quotient) {
  // By doing the check here instead of relying on "~/" below we get the
  // exception even with dart2js.
  if (quotient == 0) throw IntegerDivisionByZeroException();
  return Duration._microseconds(_duration ~/ quotient);
}

Constants

hoursPerDay

const int hoursPerDay

The number of hours per day.

Notice that some days may differ in length because of time zone changes due to daylight saving. The Duration class is time zone agnostic and considers all days to have 24 hours.

Implementation

static const int hoursPerDay = 24;

microsecondsPerDay

const int microsecondsPerDay

The number of microseconds per day.

Implementation

static const int microsecondsPerDay = microsecondsPerHour * hoursPerDay;

microsecondsPerHour

const int microsecondsPerHour

The number of microseconds per hour.

Implementation

static const int microsecondsPerHour = microsecondsPerMinute * minutesPerHour;

microsecondsPerMillisecond

const int microsecondsPerMillisecond

The number of microseconds per millisecond.

Implementation

static const int microsecondsPerMillisecond = 1000;

microsecondsPerMinute

const int microsecondsPerMinute

The number of microseconds per minute.

Implementation

static const int microsecondsPerMinute =
    microsecondsPerSecond * secondsPerMinute;

microsecondsPerSecond

const int microsecondsPerSecond

The number of microseconds per second.

Implementation

static const int microsecondsPerSecond =
    microsecondsPerMillisecond * millisecondsPerSecond;

millisecondsPerDay

const int millisecondsPerDay

The number of milliseconds per day.

Implementation

static const int millisecondsPerDay = millisecondsPerHour * hoursPerDay;

millisecondsPerHour

const int millisecondsPerHour

The number of milliseconds per hour.

Implementation

static const int millisecondsPerHour = millisecondsPerMinute * minutesPerHour;

millisecondsPerMinute

const int millisecondsPerMinute

The number of milliseconds per minute.

Implementation

static const int millisecondsPerMinute =
    millisecondsPerSecond * secondsPerMinute;

millisecondsPerSecond

const int millisecondsPerSecond

The number of milliseconds per second.

Implementation

static const int millisecondsPerSecond = 1000;

minutesPerDay

const int minutesPerDay

The number of minutes per day.

Implementation

static const int minutesPerDay = minutesPerHour * hoursPerDay;

minutesPerHour

const int minutesPerHour

The number of minutes per hour.

Implementation

static const int minutesPerHour = 60;

secondsPerDay

const int secondsPerDay

The number of seconds per day.

Implementation

static const int secondsPerDay = secondsPerHour * hoursPerDay;

secondsPerHour

const int secondsPerHour

The number of seconds per hour.

Implementation

static const int secondsPerHour = secondsPerMinute * minutesPerHour;

secondsPerMinute

const int secondsPerMinute

The number of seconds per minute.

Notice that some minutes of official clock time might differ in length because of leap seconds. The Duration and DateTime classes ignore leap seconds and consider all minutes to have 60 seconds.

Implementation

static const int secondsPerMinute = 60;

zero

const Duration zero

An empty duration, representing zero time.

Implementation

static const Duration zero = Duration(seconds: 0);