Skip to main content
A DateTime object represents a specific instant in time, expressed as a date and time of day in the Gregorian calendar. Internally, it stores the number of microseconds that have elapsed since the Unix epoch (00:00:00 UTC on January 1, 1970).

​
Instantiation

The DateTime class provides several constructors to initialize instances based on specific calendar components, existing timestamps, or ISO 8601 strings. 
// Current time in the local time zone
final now = DateTime.now();

// Specific date in the local time zone: Year, Month, Day, Hour, Minute, Second, Ms, Us
// Unspecified units default to 0.
final localDate = DateTime(2023, 10, 25, 14, 30);

// Specific date in UTC
final utcDate = DateTime.utc(2023, 10, 25, 14, 30);

// From Unix Epoch (milliseconds or microseconds)
final fromEpoch = DateTime.fromMillisecondsSinceEpoch(1698244200000);

// Parsing an ISO 8601 string
// Supports complete dates (YYYY-MM-DD) or combined date-time strings
final parsed = DateTime.parse("2023-10-25 14:30:00Z");

​
Time Zone Handling

Dart DateTime instances are anchored to one of two time zones:
  1. UTC: Coordinated Universal Time.
  2. Local: The time zone configured on the host system.
The class does not natively support arbitrary IANA time zones (e.g., America/New_York) without external libraries. 
final date = DateTime.now();

print(date.isUtc); // false (if system is not UTC)

// Conversion returns a new instance
final asUtc = date.toUtc();
final asLocal = asUtc.toLocal();

print(asUtc.isUtc); // true

​
Component Access

Read-only properties allow access to individual calendar components. 
final date = DateTime(2023, 12, 25, 10, 0, 0);

int y = date.year;        // 2023
int m = date.month;       // 12
int d = date.day;         // 25
int h = date.hour;        // 10
int wd = date.weekday;    // 1 (Monday) to 7 (Sunday)
int ms = date.millisecond;
int us = date.microsecond;

​
Immutability and Arithmetic

DateTime objects are immutable. Operations that modify the time return a new DateTime instance. Time deltas are represented by the Duration class. 
final start = DateTime(2023, 1, 1);
final duration = Duration(days: 10, hours: 5);

// Addition
final future = start.add(duration); 
// Result: 2023-01-11 05:00:00.000

// Subtraction
final past = start.subtract(Duration(seconds: 30));

// Difference calculation
// Returns a Duration object
final diff = future.difference(start);
print(diff.inHours); // 245

​
Comparison

The class implements Comparable, allowing for direct comparison of temporal order. 
final a = DateTime(2023, 1, 1);
final b = DateTime(2023, 1, 2);

bool isBefore = a.isBefore(b);          // true
bool isAfter = a.isAfter(b);            // false
bool isSame = a.isAtSameMomentAs(b);    // false
bool isEqual = (a == b);                // false (Checks value equality)

​
Platform Precision

The precision of DateTime depends on the underlying platform:
  • Dart Native (VM/AOT): Supports microsecond precision (64-bit integer).
  • Dart Web (JavaScript): Supports millisecond precision (due to the limitations of the JavaScript Date object). Microsecond values will be truncated to milliseconds.

​
String Representation

Dart provides standard methods for serializing the object to string formats. 
final date = DateTime.utc(2023, 10, 25, 14, 30);

// Human-readable, SQL-compatible format
print(date.toString()); 
// Output: 2023-10-25 14:30:00.000Z

// ISO 8601 standard format
print(date.toIso8601String()); 
// Output: 2023-10-25T14:30:00.000Z
Master Dart with Deep Grasping Methodology!Learn More