Dart DateTime

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

Tired of Poor Dart Skills? Fix That With Deep Grasping!Learn More

Methods

Constructors

Classes

Getters & Setters

Variables

Fields

Parameters

Pattern Matching

Generics

Extensions

Type Aliases

Enums

Control Flow

Loops

Error Handling

Standard Library Types

Annotations

Libraries & Imports

Built-In Types

Comments

Cascade Operators

Spread Operators

Access Operators

Type Cast & Test Operators

Conditional Operators

Arithmetic Operators

Comparison Operators

Logical Operators

Increment & Decrement Operators

Unary Operators

Bitwise Operators

Assignment Operators

Instantiation

Core Properties

Time Zone Conversion

Arithmetic Operations

Comparison Methods

Serialization and Parsing

​Instantiation

​Core Properties

​Time Zone Conversion

​Arithmetic Operations

​Comparison Methods

​Serialization and Parsing

Instantiation

Core Properties

Time Zone Conversion

Arithmetic Operations

Comparison Methods

Serialization and Parsing