Dart Duration Class

last modified May 25, 2025

The Duration class in Dart represents a time interval and is widely used for measuring time spans, scheduling tasks, and performing time-based calculations. This tutorial explores the creation, manipulation, and application of the Duration class in Dart applications.

Duration Overview

The Duration class, part of Dart's core library, provides a precise mechanism for representing time intervals in units such as days, hours, minutes, seconds, milliseconds, and microseconds. It is essential for tasks like calculating time differences, scheduling events, and managing delays in asynchronous operations.

The class is frequently used alongside DateTime to compute intervals between timestamps, schedule future events, or introduce delays. As an immutable class, Duration ensures that any modification creates a new instance, promoting safety and predictability in time-based operations.

Feature	Description	Example
Creation	Define duration with various time units	Duration(hours: 2)
Properties	Access different time components	duration.inMinutes
Arithmetic Operations	Perform addition, subtraction, or scaling	duration1 + duration2
Comparison	Compare durations using relational operators	duration1 > duration2
Formatting	Convert duration to a readable string	duration.toString()
Timers	Use duration in async operations	Future.delayed(Duration(seconds: 5))

The immutability of the Duration class ensures that its values remain unchanged after creation, with operations like addition, subtraction, and multiplication generating new instances. This design enhances reliability and simplifies debugging by preventing unintended modifications. A key application of Duration is in asynchronous programming, where it facilitates delays through Future.delayed(Duration(...)), enabling precise control over time-sensitive operations.

Creating Durations

The Duration class allows developers to define time intervals using various units, such as days, hours, minutes, seconds, milliseconds, and microseconds. All constructor parameters are optional and default to zero, providing flexibility in specifying durations. Negative values are supported, and durations are internally stored as microseconds, with a maximum range of ±2⁶³ - 1 microseconds.

void main() {

  // Different ways to create durations
  Duration hours = Duration(hours: 2);
  Duration minutes = Duration(minutes: 30);
  Duration seconds = Duration(seconds: 45);
  Duration ms = Duration(milliseconds: 500);
  Duration us = Duration(microseconds: 1000);
  
  // Combined units
  Duration complex = Duration(
    days: 1,
    hours: 3,
    minutes: 15,
    seconds: 30,
    milliseconds: 500,
    microseconds: 250
  );
  
  print('2 hours: $hours');
  print('30 minutes: $minutes');
  print('45 seconds: $seconds');
  print('500ms: $ms');
  print('1000μs: $us');
  print('Complex duration: $complex');
}

This example illustrates the creation of durations using different time units, from hours to microseconds, and demonstrates a complex duration combining multiple units.

$ dart run duration_creation.dart
2 hours: 2:00:00.000000
30 minutes: 0:30:00.000000
45 seconds: 0:00:45.000000
500ms: 0:00:00.500000
1000μs: 0:00:00.001000
Complex duration: 27:15:30.500250

Duration Properties

The Duration class provides properties to access time intervals in various units, such as inDays, inHours, inMinutes, inSeconds, inMilliseconds, and inMicroseconds. These properties return the total duration in the specified unit.

Since there are no direct properties for individual components (e.g., hours within a day), developers can use modulo arithmetic to extract specific components. For negative durations, these properties return negative values, maintaining consistency in calculations.

void main() {

  Duration duration = Duration(
    days: 1,
    hours: 2,
    minutes: 30,
    seconds: 45,
    milliseconds: 500,
    microseconds: 250
  );
  
  print('In days: ${duration.inDays}');
  print('In hours: ${duration.inHours}');
  print('In minutes: ${duration.inMinutes}');
  print('In seconds: ${duration.inSeconds}');
  print('In milliseconds: ${duration.inMilliseconds}');
  print('In microseconds: ${duration.inMicroseconds}');
  
  // Individual components
  print('Days component: ${duration.inDays}');
  print('Hours component: ${duration.inHours % 24}');
  print('Minutes component: ${duration.inMinutes % 60}');
  print('Seconds component: ${duration.inSeconds % 60}');
  print('Milliseconds component: ${duration.inMilliseconds % 1000}');
  print('Microseconds component: ${duration.inMicroseconds % 1000}');
}

This example shows how to access duration properties and extract individual components using modulo operations.

$ dart run duration_properties.dart
In days: 1
In hours: 26
In minutes: 1590
In seconds: 95445
In milliseconds: 95445500
In microseconds: 95445500250
Days component: 1
Hours component: 2
Minutes component: 30
Seconds component: 45
Milliseconds component: 500
Microseconds component: 250

Duration Arithmetic

The Duration class supports arithmetic operations such as addition, subtraction, multiplication, negation, and absolute value computation. Addition combines two durations, subtraction computes their difference, and multiplication scales a duration by an integer. Negation inverts the duration's sign, and the abs method returns the absolute value. Division, which returns a double rather than a Duration, is useful for calculating ratios between durations.

void main() {

  Duration d1 = Duration(hours: 2, minutes: 30);
  Duration d2 = Duration(minutes: 45);
  
  // Addition
  Duration sum = d1 + d2;
  print('Sum: $sum');
  
  // Subtraction
  Duration diff = d1 - d2;
  print('Difference: $diff');
  
  // Multiplication
  Duration multiplied = d1 * 3;
  print('Multiplied: $multiplied');
  
  // Division (returns double)
  double ratio = d1.inMinutes / d2.inMinutes;
  print('Ratio: $ratio');
  
  // Negation
  Duration negative = -d1;
  print('Negative: $negative');
  
  // Absolute value
  Duration absValue = negative.abs();
  print('Absolute: $absValue');
}

This example demonstrates arithmetic operations on durations, showcasing addition, subtraction, multiplication, division, negation, and absolute value calculations.

$ dart run duration_arithmetic.dart
Sum: 3:15:00.000000
Difference: 1:45:00.000000
Multiplied: 7:30:00.000000
Ratio: 3.3333333333333335
Negative: -2:30:00.000000
Absolute: 2:30:00.000000

Comparing Durations

The Duration class allows comparisons using standard operators like ==, <, >, <=, and >=, as well as the compareTo method, which returns -1, 0, or 1 based on whether the duration is less than, equal to, or greater than another. Comparisons are based on the total microseconds, and negative durations are considered less than positive ones, ensuring consistent and intuitive results.

void main() {

  Duration short = Duration(minutes: 5);
  Duration medium = Duration(minutes: 15);
  Duration long = Duration(hours: 1);
  
  print('short == medium: ${short == medium}');
  print('short < medium: ${short < medium}');
  print('medium > long: ${medium > long}');
  print('short <= medium: ${short <= medium}');
  print('long >= medium: ${long >= medium}');
  
  // CompareTo returns -1, 0, or 1
  print('short.compareTo(medium): ${short.compareTo(medium)}');
  print('medium.compareTo(medium): ${medium.compareTo(medium)}');
  print('long.compareTo(medium): ${long.compareTo(medium)}');
}

This example illustrates how to compare durations using both standard operators and the compareTo method.

Formatting Durations

The Duration class supports formatting through the toString method, which outputs durations in the format HH:MM:SS.microseconds, with a leading minus sign for negative durations. For custom formatting, developers can extract components like hours, minutes, and seconds using properties and use methods like padLeft to ensure consistent digit counts, enabling tailored string representations.

void main() {

  Duration duration = Duration(
    hours: 2,
    minutes: 15,
    seconds: 30,
    milliseconds: 500,
    microseconds: 250
  );
  
  // Standard toString() format
  print('Default format: $duration');
  
  // Custom formatting
  String formatted = [
    duration.inHours,
    duration.inMinutes.remainder(60),
    duration.inSeconds.remainder(60)
  ].map((seg) => seg.toString().padLeft(2, '0')).join(':');
  
  print('Custom format: $formatted');
  
  // For negative durations
  Duration negative = -duration;
  print('Negative format: $negative');
  
  // Formatting with milliseconds
  String withMs = '${duration.inMinutes}:${(duration.inSeconds % 60).toString().padLeft(2, '0')}.${(duration.inMilliseconds % 1000).toString().padLeft(3, '0')}';
  print('With milliseconds: $withMs');
}

This example demonstrates formatting durations using the default toString method and custom formatting techniques.

$ dart run duration_formatting.dart
Default format: 2:15:30.500250
Custom format: 02:15:30
Negative format: -2:15:30.500250
With milliseconds: 135:30.500

Working with DateTime

The Duration class is frequently used with DateTime to perform time calculations, such as moving a timestamp forward with add, backward with subtract, or computing the interval between two timestamps using difference, which returns a Duration. These operations are time zone-aware, defaulting to the local time zone, ensuring accurate handling of time-based logic.

void main() {

  DateTime now = DateTime.now();
  Duration offset = Duration(days: 7, hours: 3);
  
  // Adding duration to DateTime
  DateTime future = now.add(offset);
  print('Now: $now');
  print('Future: $future');
  
  // Subtracting duration from DateTime
  DateTime past = now.subtract(offset);
  print('Past: $past');
  
  // Difference between DateTimes is a Duration
  Duration diff = future.difference(past);
  print('Difference: $diff');
  
  // Time until/since specific DateTime
  DateTime event = DateTime(2025, 12, 25);
  Duration untilEvent = event.difference(now);
  print('Days until event: ${untilEvent.inDays}');
}

This example illustrates the use of Duration with DateTime for advancing, retracting, and calculating differences between timestamps.

$ dart run duration_datetime.dart
Now: 2025-05-25 14:30:45.123456
Future: 2025-06-01 17:30:45.123456
Past: 2025-05-18 11:30:45.123456
Difference: 336:00:00.000000
Days until event: 214

Timer Implementation

The Timer class leverages Duration to schedule tasks, enabling execution after a specified delay or at regular intervals. This is particularly useful for implementing periodic actions or timeouts in Dart applications.

import 'dart:async';

void main() {

  Duration interval = Duration(seconds: 1);
  int count = 0;
  
  Timer.periodic(interval, (timer) {
    count++;
    print('Tick $count');
    
    if (count >= 5) {
      timer.cancel();
      print('Timer stopped');
    }
  });
}

This example creates a periodic timer that triggers every second, printing a tick count until it reaches five, at which point the timer is canceled.

Delay Execution

The Future.delayed constructor, combined with Duration, allows developers to pause code execution for a specified time. This approach is ideal for simulating delays, implementing timeouts, or coordinating asynchronous operations in Dart applications.

Future<void> main() async {
    
  print('Starting...');
  
  await Future.delayed(Duration(seconds: 2));
  
  print('After 2 seconds');
}

This example uses Future.delayed to introduce a two-second delay before printing a message, demonstrating a common pattern for handling asynchronous delays.

Measuring Execution Time

The Stopwatch class, used with Duration, enables precise measurement of execution time for code segments. This is valuable for performance analysis, benchmarking, and optimizing Dart applications.

void main() {

  Stopwatch stopwatch = Stopwatch()..start();
  
  // Simulate work
  int sum = 0;
  for (int i = 0; i < 100_000_000; i++) {
    sum += i;
  }
  
  stopwatch.stop();
  print('Sum: $sum');
  print('Computation took: ${stopwatch.elapsed}');
}

This example measures the time taken to compute a sum using Stopwatch, showcasing its utility in performance profiling.

Duration in Rate Limiting

The Duration class can be used to implement rate limiting in applications, controlling the frequency of actions such as API calls or user interactions. By enforcing a minimum time interval between actions, developers can prevent overuse and ensure system stability.

import 'dart:async';

void main() async {

  Duration rateLimit = Duration(milliseconds: 500);
  int actionCount = 0;

  Future<void> performAction() async {
    actionCount++;
    print('Action $actionCount at ${DateTime.now()}');
    await Future.delayed(rateLimit);
  }

  for (int i = 0; i < 5; i++) {
    await performAction();
  }
}

This example implements a simple rate limiter that ensures actions occur at least 500 milliseconds apart. Each action is delayed using Future.delayed with a Duration, demonstrating how to control the frequency of operations in Dart applications.

Source

Dart Duration Class Documentation
Dart Library Tour: Dates and Times

The Duration class is a cornerstone of Dart's core library, vital for managing time-based operations. Mastering its creation, manipulation, and formatting is essential for building robust and efficient Dart applications.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Dart tutorials.