Skip to main content
A Duration represents a discrete, immutable span of time, independent of calendar systems, time zones, or specific clock times. Internally, it encapsulates the time difference as a signed 64-bit integer representing the total number of microseconds.

​
Instantiation and Normalization

The Duration constructor accepts named arguments for various time units ranging from days down to microseconds. All arguments are optional and default to 0. The constructor normalizes input values. If a unit exceeds its natural boundary (e.g., 65 seconds), the excess is carried over to the next larger unit. Negative values are permitted and are subtracted from the total span. 
// Standard instantiation
const d1 = Duration(days: 1, hours: 5, minutes: 30);

// Normalization: 65 seconds becomes 1 minute, 5 seconds
const d2 = Duration(minutes: 0, seconds: 65); 
print(d2); // 0:01:05.000000

// Negative values: 1 hour minus 10 minutes
const d3 = Duration(hours: 1, minutes: -10);
print(d3); // 0:50:00.000000

​
Properties and Accessors

The Duration class provides getters to retrieve the span in specific units. These accessors return the total span expressed in the requested unit, truncated to an integer. They do not return the fractional component of the time format.
  • inDays: Total days.
  • inHours: Total hours.
  • inMinutes: Total minutes.
  • inSeconds: Total seconds.
  • inMilliseconds: Total milliseconds.
  • inMicroseconds: Total microseconds (the exact internal representation).
const span = Duration(hours: 2, minutes: 30);

print(span.inHours);   // 2
print(span.inMinutes); // 150 (2 * 60 + 30)
print(span.inSeconds); // 9000
To determine the sign of the duration:
  • isNegative: Returns true if the total microseconds is less than 0.

​
Arithmetic and Comparison

Duration objects support operator overloading for arithmetic manipulation and comparison. Because the class is immutable, arithmetic operations return a new Duration instance. Arithmetic Operators:
  • + (Addition): Adds two durations.
  • - (Subtraction): Subtracts one duration from another.
  • * (Multiplication): Multiplies the duration by a number.
  • ~/ (Integer Division): Divides the duration by a number, returning a truncated Duration.
  • - (Unary Negation): Negates the duration.
const d1 = Duration(hours: 1);
const d2 = Duration(minutes: 30);

final sum = d1 + d2;       // 1 hour, 30 minutes
final diff = d1 - d2;      // 30 minutes
final doubled = d1 * 2;    // 2 hours
final half = d1 ~/ 2;      // 30 minutes
Comparison: Duration implements Comparable<Duration>, allowing the use of standard comparison operators (>, <, >=, <=, ==). 
print(Duration(hours: 1) > Duration(minutes: 50)); // true
print(Duration(seconds: 60) == Duration(minutes: 1)); // true

​
Constants

The class exposes static constants for common time calculations:
  • Duration.zero: An empty duration (0 microseconds).
  • Duration.microsecondsPerMillisecond: 1000
  • Duration.millisecondsPerSecond: 1000
  • Duration.secondsPerMinute: 60
  • Duration.minutesPerHour: 60
  • Duration.hoursPerDay: 24
Master Dart with Deep Grasping Methodology!Learn More