> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```dart theme={"dark"} // 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. ```dart theme={"dark"} 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. ```dart theme={"dark"} 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. ```dart theme={"dark"} 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. ```dart theme={"dark"} 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` 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`. ```dart theme={"dark"} 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. ```dart theme={"dark"} 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