DateTime object in Dart

What is DateTime class?

A DateTime object is a point in time. The time zone is either UTC or the local time zone.

You can create DateTime objects using several constructors:

DateTime now method

The now() method is to get the current date and time in the local time zone.

The following code snippet shows how to construct a DateTime instance with current date and time.

main() {
  var now = DateTime.now();

  print(now);
}

DateTime constructor

The DateTime() constructor is to create a specified DateTime with the local time zone.

The following code snippet shows how to create a new DateTime object representing the 15th of June 2020, 5.30pm

main(List<String> args) {
  var event = new DateTime(2020, 6, 15, 17, 30);

  print(event); // 2020-06-15 17:30:00.000
}

DateTime utc method

The utc() method is to create a specified DateTime in the UTC time zone.

The following code snippet shows how to construct a DateTime instance specified in the UTC time zone.

main(List<String> args) {
  var dateTimeUtc = DateTime.utc(2020, 6, 15, 17, 30);

  print(dateTimeUtc); // 2020-06-15 17:30:00.000Z
}

Note: When dealing with dates or historic events prefer to use UTC DateTimes,since they are unaffected by daylight-saving changes and are unaffected by the local timezone.

DateTime fromMillisecondsSinceEpoch method

The fromMillisecondsSinceEpoch() method is to specify a date and time in ms in the given time zone (local or UTC).

The following code snippet shows how to construct a new DateTime instance with the given millisecondsSinceEpoch.

main() {
  var dateTimeUtc =
      DateTime.fromMillisecondsSinceEpoch(946684800000, isUtc: true);

  print(dateTimeUtc); // 2000-01-01 00:00:00.000Z
}

Note: If [isUtc] is false then the date is in the local time zone. Defaults to false.

DateTime parse method

The parse() method is to create a new DateTime object from the formatted string.

The following code snippet shows how to construct a new DateTime instance based on given formatted String.

main() {
  var dateTimeUtc = DateTime.parse('2020-01-01T00:00:00Z');

  print(dateTimeUtc); // 2020-01-01 00:00:00.000Z
}

millisecondsSinceEpoch property

The millisecondsSinceEpoch property of a date returns the number of milliseconds since the “Unix epoch”—January 1, 1970, UTC. This value is independent of the time zone.

The following code snippet shows how to use millisecondsSinceEpoch property.

main() {
  var dateTime = DateTime.utc(2000);

  dateTime.millisecondsSinceEpoch;

  print(dateTime.millisecondsSinceEpoch); // 946684800000

  var unixEpoch = DateTime.utc(1970);

  unixEpoch.millisecondsSinceEpoch;

  print(unixEpoch.millisecondsSinceEpoch); // 0
}

Duration class

The Duration class is to calculate the difference between two dates and to shift a date forward or backward.

add method

The add() method is to add duration to the DateTime object.

The following code snippet shows how to return a new DateTime instance with duration added to this DateTime object.

main() {
  var today = new DateTime.now();
  var fiftyDaysFromNow = today.add(new Duration(days: 50));

  print(fiftyDaysFromNow);
}

Notice that the duration being added is actually 50 _ 24 _ 60 * 60 seconds. If the resulting DateTime has a different daylight saving offset than this, then the result won't have the same time-of-day as this, and may not even hit the calendar date 50 days later.

Be careful when working with dates in local time.

year month, day property

The following code snippet shows how to get year, month and day from DateTime instance.

main() {
  var dateTime = DateTime(2020, 6, 15);

  print(dateTime.year); // 2020

  print(dateTime.month); // 6

  print(dateTime.day); // 15
}

difference method

The difference() method is to calculate the difference between two dates, and returns a Duration object.

The following code snippet shows how to return a Duration with the difference between this and other DateTime objects.

main() {
  var thisYearEvent = DateTime(2019, 4, 12);

  var lastYearEvent = DateTime(2020, 6, 15);

  var duration = lastYearEvent.difference(thisYearEvent);

  print(duration); // 10320:00:00.000000 seconds
}

Note: The difference is measured in seconds and fractions of seconds.

inDays property

The following code snippet shows how to get the duration in days.

main() {
  var thisYearEvent = DateTime(2019, 4, 12);

  var lastYearEvent = DateTime(2020, 6, 15);

  var duration = lastYearEvent.difference(thisYearEvent);

  print(duration.inDays); // 430
}