An instant in time, such as July 20, 1969, 8:18pm GMT.

DateTimes can represent time values that are at a distance of at most100,000,000 days from epoch (1970-01-01 UTC): -271821-04-20 to 275760-09-13.

Create aDateTime object by using one of the constructorsor by parsing a correctly formatted string,which complies with a subset of ISO 8601.Note: hours are specified between 0 and 23,as in a 24-hour clock.

For example:

final now = DateTime.now();final berlinWallFell = DateTime.utc(1989, 11, 9);final moonLanding = DateTime.parse('1969-07-20 20:18:04Z'); // 8:18pm

ADateTime object is anchored either in the UTC time zoneor in the local time zone of the current computerwhen the object is created.

Once created, neither the value nor the time zoneof aDateTime object may be changed.

You can use properties to getthe individual units of aDateTime object.

print(berlinWallFell.year); // 1989print(berlinWallFell.month); // 11print(berlinWallFell.day); // 9print(moonLanding.hour); // 20print(moonLanding.minute); // 18

For convenience and readability,theDateTime class provides a constant for eachday andmonthname - for example,august andfriday.You can use these constants to improve code readability:

final berlinWallFell = DateTime.utc(1989, DateTime.november, 9);print(DateTime.november); // 11assert(berlinWallFell.month == DateTime.november);assert(berlinWallFell.weekday == DateTime.thursday);

Day andmonth values begin at 1, and the week starts onMonday.That is, the constantsjanuary andmonday are both 1.

Working with UTC and local time

ADateTime object is in the local time zoneunless explicitly created in the UTC time zone.UseisUtc to determine whether aDateTime object is based in UTC.

final dDay = DateTime.utc(1944, 6, 6);print(dDay.isUtc); // truefinal dDayLocal = DateTime(1944, 6, 6);print(dDayLocal.isUtc); // false

Use the methodstoLocal andtoUtcto get the equivalent date/time value specified in the other time zone.

final localDay = dDay.toLocal(); // e.g. 1944-06-06 02:00:00.000print(localDay.isUtc); // falsefinal utcFromLocal = localDay.toUtc(); // 1944-06-06 00:00:00.000Zprint(utcFromLocal.isUtc); // true

UsetimeZoneName to get an abbreviated name of the time zonefor theDateTime object.

print(dDay.timeZoneName); // UTCprint(localDay.timeZoneName); // e.g. EET

To find the differencebetween UTC and the time zone of aDateTime objectcalltimeZoneOffset.

print(dDay.timeZoneOffset); // 0:00:00.000000print(localDay.timeZoneOffset); // e.g. 2:00:00.000000

Comparing DateTime objects

TheDateTime class contains methods for comparingDateTimeschronologically, such asisAfter,isBefore, andisAtSameMomentAs.

print(berlinWallFell.isAfter(moonLanding)); // trueprint(berlinWallFell.isBefore(moonLanding)); // falseprint(dDay.isAtSameMomentAs(localDay)); // true

Using DateTime with Duration

Use theadd andsubtract methods with aDuration objectto create aDateTime object based on another.For example, to find the point in time that is 36 hours after now,you can write:

final now = DateTime.now();final later = now.add(const Duration(hours: 36));

To find out how much time is between twoDateTime objects usedifference, which returns aDuration object:

final difference = berlinWallFell.difference(moonLanding);print(difference.inDays); // 7416

The difference between two dates in different time zonesis just the number of nanoseconds between the two points in time.It doesn't take calendar days into account.That means that the difference between two midnights in local time may beless than 24 hours times the number of days between them,if there is a daylight saving change in between.If the difference above is calculated using Australian local time, thedifference is 7415 days and 23 hours, which is only 7415 whole days asreported byinDays.

Other resources

• SeeDuration to represent a span of time.
• SeeStopwatch to measure timespans.
• TheDateTime class does not provide internationalization. To internationalize your code, use theintl package.

Implemented types

• Comparable<DateTime>

Available extensions

• DateTimeCopyWith

Constructors

DateTime(intyear, [intmonth =1,intday =1,inthour =0,intminute =0,intsecond =0,intmillisecond =0,intmicrosecond =0])

Constructs aDateTime instance specified in the local time zone.

DateTime.fromMicrosecondsSinceEpoch(intmicrosecondsSinceEpoch, {boolisUtc =false})

Constructs a newDateTime instancewith the givenmicrosecondsSinceEpoch.

DateTime.fromMillisecondsSinceEpoch(intmillisecondsSinceEpoch, {boolisUtc =false})

Constructs a newDateTime instancewith the givenmillisecondsSinceEpoch.

DateTime.now()

Constructs aDateTime instance with current date and time in thelocal time zone.

DateTime.timestamp()

Constructs aDateTime with the current UTC date and time.

DateTime.utc(intyear, [intmonth =1,intday =1,inthour =0,intminute =0,intsecond =0,intmillisecond =0,intmicrosecond =0])

Constructs aDateTime instance specified in the UTC time zone.

Properties

day→int

The day of the month[1..31].

no setter

hashCode→int

The hash code for this object.

no setteroverride

hour→int

The hour of the day, expressed as in a 24-hour clock[0..23].

no setter

isUtc→bool

True if thisDateTime is set to UTC time.

final

microsecond→int

The microsecond[0...999].

no setter

microsecondsSinceEpoch→int

The number of microseconds sincethe "Unix epoch" 1970-01-01T00:00:00Z (UTC).

no setter

millisecond→int

The millisecond[0...999].

no setter

millisecondsSinceEpoch→int

The number of milliseconds sincethe "Unix epoch" 1970-01-01T00:00:00Z (UTC).

no setter

minute→int

The minute[0...59].

no setter

month→int

The month[1..12].

no setter

runtimeType→Type

A representation of the runtime type of the object.

no setterinherited

second→int

The second[0...59].

no setter

timeZoneName→String

The time zone name.

no setter

timeZoneOffset→Duration

The time zone offset, whichis the difference between local time and UTC.

no setter

weekday→int

The day of the weekmonday..sunday.

no setter

year→int

The year.

no setter

Methods

add(Durationduration)→DateTime

Returns a newDateTime instance withduration added to thisDateTime.

compareTo(DateTimeother)→int

Compares this DateTime object toother,returning zero if the values are equal.

override

copyWith({int?year,int?month,int?day,int?hour,int?minute,int?second,int?millisecond,int?microsecond,bool?isUtc})→DateTime

Available onDateTime, provided by theDateTimeCopyWith extension

Creates a newDateTime from this one by updating individual properties.

difference(DateTimeother)→Duration

Returns aDuration with the difference when subtractingother fromthisDateTime.

isAfter(DateTimeother)→bool

Whether thisDateTime occurs afterother.

isAtSameMomentAs(DateTimeother)→bool

Whether thisDateTime occurs at the same moment asother.

isBefore(DateTimeother)→bool

Whether thisDateTime occurs beforeother.

noSuchMethod(Invocationinvocation)→ dynamic

Invoked when a nonexistent method or property is accessed.

inherited

subtract(Durationduration)→DateTime

Returns a newDateTime instance withduration subtracted from thisDateTime.

toIso8601String()→String

Returns an ISO-8601 full-precision extended format representation.

toLocal()→DateTime

Returns this DateTime value in the local time zone.

toString()→String

Returns a human-readable string for this instance.

override

toUtc()→DateTime

Returns this DateTime value in the UTC time zone.

Operators

operator ==(Objectother)→bool

Whetherother is aDateTime at the same moment and in thesame time zone (UTC or local).

override

Static Methods

parse(StringformattedString)→DateTime

Constructs a newDateTime instance based onformattedString.

tryParse(StringformattedString)→DateTime?

Constructs a newDateTime instance based onformattedString.

Constants

april→ constint

august→ constint

daysPerWeek→ constint

december→ constint

february→ constint

friday→ constint

january→ constint

july→ constint

june→ constint

march→ constint

may→ constint

monday→ constint

monthsPerYear→ constint

november→ constint

october→ constint

saturday→ constint

september→ constint

sunday→ constint

thursday→ constint

tuesday→ constint

wednesday→ constint