class
DateTime

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

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

DateTime now = new DateTime.now();
DateTime berlinWallFell = new DateTime(1989, 11, 9);
DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");  // 8:18pm

A DateTime object is anchored either in the UTC time zone or in the local time zone of the current computer when the object is created.

Once created, neither the value nor the time zone of a DateTime object may be changed.

You can use properties to get the individual units of a DateTime object.

assert(berlinWallFell.month == 11);
assert(moonLanding.hour == 20);

For convenience and readability, the DateTime class provides a constant for each day and month name—for example, AUGUST and FRIDAY. You can use these constants to improve code readibility:

DateTime berlinWallFell = new DateTime(1989, DateTime.NOVEMBER, 9);
assert(berlinWallFell.weekday == DateTime.THURSDAY);

Day and month values begin at 1, and the week starts on Monday. That is, the constants JANUARY and MONDAY are both 1.

Working with UTC and local time

A DateTime object is in the local time zone unless explicitly created in the UTC time zone.

DateTime dDay = new DateTime.utc(1944, 6, 6);

Use isUtc to determine whether a DateTime object is based in UTC. Use the methods toLocal and toUtc to get the equivalent date/time value specified in the other time zone. Use timeZoneName to get an abbreviated name of the time zone for the DateTime object. To find the difference between UTC and the time zone of a DateTime object call timeZoneOffset.

Comparing DateTime objects

The DateTime class contains several handy methods, such as isAfter, isBefore, and isAtSameMomentAs, for comparing DateTime objects.

assert(berlinWallFell.isAfter(moonLanding) == true);
assert(berlinWallFell.isBefore(moonLanding) == false);

Using DateTime with Duration

Use the add and subtract methods with a Duration object to create a new DateTime object based on another. For example, to find the date that is sixty days after today, write:

DateTime today = new DateTime.now();
DateTime sixtyDaysFromNow = today.add(new Duration(days: 60));

To find out how much time is between two DateTime objects use difference, which returns a Duration object:

Duration difference = berlinWallFell.difference(moonLanding)
assert(difference.inDays == 7416);

The difference between two dates in different time zones is 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 be less 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, the difference is 7415 days and 23 hours, which is only 7415 whole days as reported by inDays.

Other resources

See Duration to represent a span of time. See Stopwatch to measure timespans.

The DateTime class does not provide internationalization. To internationalize your code, use the intl package.

Implements

Constants

int MONDAY = 1
const
int TUESDAY = 2
const
int WEDNESDAY = 3
const
int THURSDAY = 4
const
int FRIDAY = 5
const
int SATURDAY = 6
const
int SUNDAY = 7
const
int DAYS_PER_WEEK = 7
const
int JANUARY = 1
const
int FEBRUARY = 2
const
int MARCH = 3
const
int APRIL = 4
const
int MAY = 5
const
int JUNE = 6
const
int JULY = 7
const
int AUGUST = 8
const
int SEPTEMBER = 9
const
int OCTOBER = 10
const
int NOVEMBER = 11
const
int DECEMBER = 12
const
int MONTHS_PER_YEAR = 12
const

Static Methods

parse(String formattedString) → DateTime
Constructs a new DateTime instance based on formattedString.

Properties

int millisecondsSinceEpoch
read-only
The number of milliseconds since the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
bool isUtc
read-only
True if this DateTime is set to UTC time.
int hashCode
read-only
String timeZoneName
read-only
The abbreviated time zone name—for example, "CET" or "CEST".
Duration timeZoneOffset
read-only
The time zone offset, which is the difference between local time and UTC.
int year
read-only
The year.
int month
read-only
The month [1..12].
int day
read-only
The day of the month [1..31].
int hour
read-only
The hour of the day, expressed as in a 24-hour clock [0..23].
int minute
read-only
The minute [0...59].
int second
read-only
The second [0...59].
int millisecond
read-only
The millisecond [0...999].
int weekday
read-only
The day of the week [MONDAY]..[SUNDAY].

Constructors

DateTime(int year, [int month = 1, int day = 1, int hour = 0, int minute = 0, int second = 0, int millisecond = 0])
Constructs a DateTime instance specified in the local time zone.
DateTime.utc(int year, [int month = 1, int day = 1, int hour = 0, int minute = 0, int second = 0, int millisecond = 0])
Constructs a DateTime instance specified in the UTC time zone.
DateTime.now()
Constructs a DateTime instance with current date and time in the local time zone.
DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch, {bool isUtc: false})
Constructs a new DateTime instance with the given millisecondsSinceEpoch.

Operators

operator ==(other) → bool
Returns true if other is a DateTime at the same moment and in the same time zone (UTC or local).

Methods

isBefore(DateTime other) → bool
Returns true if this occurs before other.
isAfter(DateTime other) → bool
Returns true if this occurs after other.
isAtSameMomentAs(DateTime other) → bool
Returns true if this occurs at the same moment as other.
compareTo(DateTime other) → int
Compares this DateTime object to other, returning zero if the values are equal.
toLocal() → DateTime
Returns this DateTime value in the local time zone.
toUtc() → DateTime
Returns this DateTime value in the UTC time zone.
toString() → String
Returns a human-readable string for this instance.
toIso8601String() → String
Returns an ISO-8601 full-precision extended format representation.
add(Duration duration) → DateTime
Returns a new DateTime instance with duration added to this.
subtract(Duration duration) → DateTime
Returns a new DateTime instance with duration subtracted from this.
difference(DateTime other) → Duration
Returns a Duration with the difference between this and other.