Dart Time #

• Dart Time
  • What's Included
    • Extensions
    • Specialized Classes
    • Key Features
  • Installation
  • Usage
  • API Quick Reference
    • Extensions
      • DateTimeHelper - Enhanced DateTime
      • IterableDateTimeHelper - Enhanced Iterable
      • DurationHelper - Enhanced Duration
      • IntDurationHelper & DoubleDurationHelper
    • Classes
      • ClockTime - Time without Date
      • ClockTimeRange - Time Ranges
      • DartDateRange - Date Ranges
      • ISODuration - ISO 8601 Durations
      • WorkCalendar - Work Calendar
      • ActivityScheduler - Activity Scheduler
    • TimeGranularity Enum

A comprehensive Dart library that extends and enhances Dart's built-in time functionality. This library provides powerful extensions to DateTime and Duration, plus specialized classes for advanced time operations.

What's Included #

Extensions #

Enhance existing Dart types with additional functionality:

• DateTimeHelper - Extends DateTime with 50+ methods for date manipulation, boundary calculations, granular comparisons, and DST-aware arithmetic
• DurationHelper - Extends Duration with formatting, validation, rounding, and ISO 8601 conversion
• IntDurationHelper - Extends int to create durations easily (e.g., 5.days, 30.minutes)
• NumDurationHelper - Extends num for fractional durations (e.g., 2.5.fractionalHours)
• IterableDateTimeHelper - Extends Iterable<DateTime> with helper methods for dates manipulation

Specialized Classes #

New types for specific time-related operations:

• ClockTime - Represents time-of-day (14:30:45) without date information, with 12/24-hour formatting and time-period detection
• ClockTimeRange - Represents time ranges for schedule management and time-based filtering
• DartDateRange - Powerful date range operations with iteration, overlap detection, and boundary calculations
• ISODuration - Full ISO 8601 duration support with positive/negative durations and component-based operations
• WorkCalendar - Provides utilities for working days and holidays
• ActivityScheduler - Provides utilities for finding available time slots for scheduling

Key Features #

• DST-Aware Operations: Handle Daylight Saving Time transitions correctly
• Granular Time Comparisons: Compare dates/times at different precision levels (year, month, day, hour, etc.)
• ISO 8601 Compliance: Full standard support for durations and week numbering
• Flexible Formatting: Multiple output formats for different use cases
• Comprehensive Range Operations: Overlap detection, intersection, iteration through time periods
• Type Safety: Immutable objects with clear APIs and extensive validation

Installation #

❗ In order to start using Dart Time you must have the Dart SDK installed on your machine (minimum Dart SDK version: 2.14.0 (09/2021))

Install via dart pub add:

dart pub add dart_time

Usage #

import 'package:dart_time/dart_time.dart';

void main() {
  // 🔧 DateTime Extensions - Enhanced date manipulation
  final date = DateTime(2023, 6, 15, 14, 30);
  
  print(date.startOfDay);        // 2023-06-15 00:00:00.000
  print(date.endOfMonth);        // 2023-06-30 23:59:59.999
  print(date.addMonths(2));      // 2023-08-15 14:30:00.000
  print(date.quarter);           // 2 (second quarter)
  print(date.isLeapYear);        // false
  print(date.daysInMonth);       // 30
  
  // 🔧 Duration Extensions - Easy duration creation and formatting
  final duration = 2.5.fractionalHours;  // 2 hours 30 minutes
  print(duration.hhmmss);                 // "02:30:00"
  print(duration.inFractionalHours);      // 2.5
  print(90.minutes.roundToHour());        // 1 hour
  
  // 📅 ClockTime - Time-of-day operations without dates
  final meetingTime = ClockTime(14, minute: 30);  // 2:30 PM
  print(meetingTime.format12Hour);                 // "2:30 PM"
  print(meetingTime.isAfternoon);                  // true
  print(meetingTime.minutesSinceMidnight);         // 870
  
  final lunchBreak = ClockTimeRange(
    start: ClockTime(12),
    end: ClockTime(13),
  );
  
  // 📅 Date Ranges - Powerful range operations
  final quarter = DartDateRange(
    start: DateTime(2023, 7, 1),   // Q3 start
    end: DateTime(2023, 9, 30),    // Q3 end
  );
  
  print(quarter.duration.inDays);        // 92 days
  print(quarter.includes(DateTime(2023, 8, 15)));  // true
  
  // Iterate through all Mondays in the quarter
  final mondays = quarter.dates
    .where((date) => date.weekday == DateTime.monday)
    .toList();
  
  // 📅 ISO Duration - Standards-compliant duration handling
  final projectDuration = ISODuration.parse('P1Y2M15DT5H30M');
  print(projectDuration.years);          // 1
  print(projectDuration.months);         // 2
  print(projectDuration.days);           // 15
  print(projectDuration.toIso());        // "P1Y2M15DT5H30M"
  
  // Negative durations supported
  final timeAgo = ISODuration.parse('-P6M');  // 6 months ago
  print(timeAgo.isNegative);                  // true

  // 📅 Work Calendar - Working days and holidays
  final calendar = WorkCalendar(
    workingDays: const {
      DateTime.monday,
      DateTime.tuesday,
      DateTime.wednesday,
      DateTime.thursday,
      DateTime.friday,
    },
    holidays: {
      DateTime(2023, 6, 15),
    },
  );
  print(calendar.isWorkingDay(DateTime(2023, 6, 15))); // false
  print(calendar.isHoliday(DateTime(2023, 6, 15))); // true

  // 📅 Activity Scheduler - Find available time slots
  final availableSlots = ActivityScheduler.findAvailableSlots(
    period: DartDateRange(start: DateTime(2023, 6, 15), end: DateTime(2023, 6, 19)),
    slotDuration: Duration(hours: 1),
    busySlots: [],
    maxSlots: 2,
    workingHours: (date) => [workHours],
  );
  print(availableSlots); // [2023-06-15 09:00:00.000, 2023-06-15 10:00:00.000]
  final nextSlot = ActivityScheduler.findNextSlot(
    from: DateTime.now(),
    slotDuration: Duration(hours: 1),
    slotInterval: Duration(minutes: 15),
    busySlots: [],
    workingHours: (date) => [workHours],
  );
  print(nextSlot); // 2023-06-15 09:00:00.000
}

API Quick Reference #

💡 Tip: For complete API documentation with all methods and parameters, see the full documentation.

Extensions #

DateTimeHelper - Enhanced DateTime

Extends DateTime with 50+ additional methods:

Boundaries & Navigation

date.startOfDay, date.endOfMonth, date.nextDay, date.previousDay
date.startOfQuarter, date.endOfYear, date.quarter

Calendar Information

date.isLeapYear, date.daysInMonth, date.daysInYear
date.isoWeekOfYear, date.isSameWeek(other)

DST-Aware Arithmetic

date.addMonths(2), date.addDays(5, ignoreDaylightSavings: true)
date.subYears(1), date.addHours(3)

Granular Comparisons

date.isSameDay(other), date.isSameMonth(other)
date.isGranularAfter(other, TimeGranularity.hour)

Date Comparison

date.isFuture, date.isPast
date.isMonday, date.isTuesday, date.isWednesday, date.isThursday, date.isFriday, date.isSaturday, date.isSunday
date.isWeekend, date.isWeekday

IterableDateTimeHelper - Enhanced Iterable

Extends Iterable<DateTime> with helper methods for date manipulation:

dates.max();
dates.min();

DurationHelper - Enhanced Duration

Extends Duration with formatting and utilities:

duration.hhmmss              // "02:30:00"
duration.inFractionalHours   // 2.5
duration.roundToHour()       // Round to nearest hour
duration.isLongerThan(other) // Comparison

IntDurationHelper & DoubleDurationHelper

Easy duration creation from numbers:

5.days                  // Duration(days: 5)
30.minutes             // Duration(minutes: 30)  
2.5.fractionalHours    // 2 hours 30 minutes

Classes #

ClockTime - Time without Date

Represents time-of-day independently from dates:

ClockTime(14, minute: 30)         // 2:30 PM
ClockTime.parse("14:30:45")       // Parse time string
time.format12Hour                 // "2:30 PM"
time.isAfternoon                  // true
time.addHours(2)                  // 4:30 PM

ClockTimeRange - Time Ranges

final workHours = ClockTimeRange(
  start: ClockTime(9),   // 9:00 AM
  end: ClockTime(17),    // 5:00 PM
);
workHours.includes(DateTime.now());

DartDateRange - Date Ranges

Powerful date range operations:

final quarter = DartDateRange(
  start: DateTime(2023, 7, 1),
  end: DateTime(2023, 9, 30),
);

quarter.duration.inDays         // 92
quarter.includes(someDate)      // true/false
quarter.dates.toList()          // All dates in range
quarter.cross(otherRange)       // Check overlap

ISODuration - ISO 8601 Durations

Full ISO 8601 duration support with negative durations:

ISODuration.parse("P1Y2M3DT4H30M")   // 1 year, 2 months, 3 days, 4h 30m
ISODuration.parse("-P6M")            // 6 months ago
duration.toIso()                     // Convert back to string
duration.isNegative                  // Check if negative

WorkCalendar - Work Calendar

Provides utilities for working days and holidays

final calendar = WorkCalendar();
print(calendar.isWorkingDay(DateTime(2023, 6, 15)));

ActivityScheduler - Activity Scheduler

Provides utilities for finding available time slots for scheduling activities, meetings, or appointments

final availableSlots = ActivityScheduler.findAvailableSlots(
  period: DartDateRange(start: DateTime(2023, 6, 15), end: DateTime(2023, 6, 19)),
  slotDuration: Duration(hours: 1),
  busySlots: [],
  workingHours: (date) => [workHours],
);
print(availableSlots);
final nextSlot = ActivityScheduler.findNextSlot(
  from: DateTime.now(),
  slotDuration: Duration(hours: 1),
  slotInterval: Duration(minutes: 15),
  busySlots: [],
  workingHours: (date) => [workHours],
);
print(nextSlot);

TimeGranularity Enum #

Control precision for comparisons:

TimeGranularity.year      // Compare by year only
TimeGranularity.month     // Compare by month
TimeGranularity.day       // Compare by day
TimeGranularity.hour      // Compare by hour
// ... and more: minute, second, milliseconds, microseconds