Dart Duration - SyntBlaze

A Duration in Dart is an immutable class representing a continuous span of time. It measures a relative time interval independent of any specific calendar date, time zone, or clock. Internally, Dart normalizes and stores all Duration instances as a single integer value of microseconds.

Instantiation

The Duration constructor accepts named, optional integer arguments. Because the class normalizes the input into a single microsecond integer, arguments can be negative or exceed standard time boundaries (e.g., passing 90 minutes is perfectly valid and evaluates to 1 hour and 30 minutes).

const Duration({
  int days = 0,
  int hours = 0,
  int minutes = 0,
  int seconds = 0,
  int milliseconds = 0,
  int microseconds = 0,
});

// Example instantiation
final exactTime = Duration(days: 2, hours: 14, minutes: 45);
final overflowTime = Duration(minutes: 90); // Normalized to 1 hour, 30 minutes
final negativeTime = Duration(hours: -2);   // Represents a negative span

Property Accessors

Duration provides getter properties to extract the time span. These properties return the total duration truncated to the requested unit, rather than the isolated component passed to the constructor.

final span = Duration(days: 1, hours: 2);

// Returns the entire span converted to the specified unit
print(span.inDays);          // 1
print(span.inHours);         // 26
print(span.inMinutes);       // 1560
print(span.inSeconds);       // 93600
print(span.inMilliseconds);  // 93600000
print(span.inMicroseconds);  // 93600000000

// Returns true if the total microsecond count is less than zero
print(span.isNegative);      // false

Arithmetic Operators

Duration supports operator overloading for standard arithmetic, allowing direct mathematical operations between Duration instances or between a Duration and a numeric scalar.

final d1 = Duration(hours: 2);
final d2 = Duration(minutes: 30);

// Binary operations with other Durations
final sum = d1 + d2;         // Duration(hours: 2, minutes: 30)
final difference = d1 - d2;  // Duration(hours: 1, minutes: 30)

// Unary negation
final negated = -d1;         // Duration(hours: -2)

// Scalar operations (multiplying/dividing the underlying microseconds)
final scaled = d1 * 2;       // Duration(hours: 4)
final divided = d1 ~/ 3;     // Duration(minutes: 40) - Note: requires integer division (~/)

Relational Operators

Because Duration implements Comparable<Duration>, instances can be compared using standard relational operators. Comparisons are evaluated based on the underlying microsecond integer.

final d1 = Duration(seconds: 60);
final d2 = Duration(minutes: 1);
final d3 = Duration(seconds: 90);

print(d1 == d2); // true
print(d1 < d3);  // true
print(d3 >= d2); // true

Core Methods

Duration exposes utility methods for absolute value conversion and explicit comparison.

final negativeDuration = Duration(seconds: -15);

// Returns a new Duration with a positive microsecond value
final absolute = negativeDuration.abs(); // Duration(seconds: 15)

// Returns an integer indicating sort order (-1, 0, or 1)
final comparison = absolute.compareTo(negativeDuration); // 1