Dart DateTime - SyntBlaze

The DateTime class in Dart represents an immutable, instantaneous point in time, evaluated within the Gregorian calendar system. It encapsulates both date and time components, operates with up to microsecond precision, and natively supports both the local system time zone and Coordinated Universal Time (UTC).

Instantiation

DateTime objects are instantiated using the default constructor for local time, or via several named constructors for specific time contexts and parsing.

// Default constructor (Local time)
// Signature: DateTime(int year, [int month = 1, int day = 1, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0])
DateTime localDate = DateTime(2023, 10, 31, 14, 30);

// UTC constructor
DateTime utcDate = DateTime.utc(2023, 10, 31, 14, 30);

// Current system time
DateTime now = DateTime.now();

// Instantiation from Unix epoch (January 1, 1970, 00:00:00 UTC)
DateTime fromEpoch = DateTime.fromMillisecondsSinceEpoch(1698762600000, isUtc: true);

Core Properties

Once instantiated, a DateTime object exposes its individual chronological components as integer properties. Because DateTime is immutable, these properties are read-only.

DateTime dt = DateTime(2023, 10, 31, 14, 30, 45, 100, 50);

int y = dt.year;           // 2023
int m = dt.month;          // 10 (1 = January, 12 = December)
int d = dt.day;            // 31
int w = dt.weekday;        // 2 (1 = Monday, 7 = Sunday)
int h = dt.hour;           // 14 (24-hour clock)
int min = dt.minute;       // 30
int sec = dt.second;       // 45
int ms = dt.millisecond;   // 100
int us = dt.microsecond;   // 50

bool isUtc = dt.isUtc;     // false

Time Zone Conversion

Dart handles time zones strictly as either Local or UTC. You can project a DateTime instance from one context to the other.

DateTime local = DateTime(2023, 10, 31);
DateTime asUtc = local.toUtc();
DateTime backToLocal = asUtc.toLocal();

// Accessing time zone metadata
String tzName = local.timeZoneName;       // e.g., "EST" or "CET"
Duration offset = local.timeZoneOffset;   // e.g., -5:00:00.000000

Arithmetic Operations

Dart distinguishes between absolute time arithmetic and calendar time arithmetic. This distinction is critical when dealing with local time, as Daylight Saving Time (DST) transitions can alter the length of a calendar day. Absolute Time Arithmetic The add and subtract methods apply a Duration (an absolute number of microseconds) to a DateTime. Because a Duration of 1 day is exactly 24 hours, adding it to a local DateTime across a DST boundary will shift the resulting local wall-clock time. To guarantee deterministic absolute arithmetic, operations should be performed in UTC.

DateTime baseUtc = DateTime.utc(2023, 10, 31, 12, 0);
Duration interval = Duration(days: 5, hours: 2);

// Addition
DateTime futureUtc = baseUtc.add(interval);      // 2023-11-05 14:00:00.000Z

// Subtraction
DateTime pastUtc = baseUtc.subtract(interval);   // 2023-10-26 10:00:00.000Z

// Calculating the delta between two DateTime objects
Duration delta = futureUtc.difference(baseUtc);  // 122:00:00.000000

Calendar Time Arithmetic To shift calendar dates safely without DST anomalies (e.g., adding exactly 5 calendar days while preserving the local hour), use the DateTime constructor to overflow the specific date components. Dart automatically normalizes out-of-bounds values.

DateTime baseLocal = DateTime(2023, 10, 31, 12, 0);

// Safe calendar addition: preserves the 12:00 local time regardless of DST shifts
DateTime futureLocal = DateTime(
  baseLocal.year,
  baseLocal.month,
  baseLocal.day + 5, // Overflows to November 5 automatically
  baseLocal.hour,
  baseLocal.minute,
); 

Comparison Methods

DateTime implements Comparable<DateTime> and provides semantic methods for chronological comparison. Dart does not overload standard relational operators (<, >, <=, >=) for DateTime; attempting to use them results in a compile-time error. Developers must use isBefore, isAfter, or compareTo. Additionally, the equality operator (==) evaluates both the absolute moment in time and the time zone state (UTC vs. Local). To compare absolute moments regardless of time zone, use isAtSameMomentAs.

DateTime dtLocal = DateTime(2023, 10, 31, 12, 0);
DateTime dtUtc = dtLocal.toUtc();

bool earlier = dtLocal.isBefore(dtUtc);            // false
bool later = dtLocal.isAfter(dtUtc);               // false

// Chronological comparison (-1, 0, 1)
int comparison = dtLocal.compareTo(dtUtc);         // 0

// Absolute moment comparison (ignores time zone state)
bool sameMoment = dtLocal.isAtSameMomentAs(dtUtc); // true

// Equality operator (requires same moment AND same time zone state)
bool isEqual = (dtLocal == dtUtc);                 // false

Serialization and Parsing

Dart natively supports the ISO-8601 standard for serializing DateTime objects to strings and parsing strings back into DateTime objects.

DateTime dt = DateTime.utc(2023, 10, 31, 14, 30);

// Serialization
String isoString = dt.toIso8601String(); 
// Output: "2023-10-31T14:30:00.000Z"

// Parsing (Throws FormatException if invalid)
DateTime parsed = DateTime.parse("2023-10-31T14:30:00.000Z");

// Safe Parsing (Returns null if invalid)
DateTime? safeParsed = DateTime.tryParse("invalid-date-string"); 
// Output: null