Dart API

Appearance

dart:core›Classes›DateTime

DateTime ​

class DateTime implements Comparable<DateTime>

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

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

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: hours are specified between 0 and 23, as in a 24-hour clock.

For example:

dart
final now = DateTime.now();
final berlinWallFell = DateTime.utc(1989, 11, 9);
final moonLanding = DateTime.parse('1969-07-20 20:18:04Z'); // 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.

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

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 readability:

dart
final berlinWallFell = DateTime.utc(1989, DateTime.november, 9);
print(DateTime.november); // 11
assert(berlinWallFell.month == DateTime.november);
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. Use isUtc to determine whether a DateTime object is based in UTC.

dart
final dDay = DateTime.utc(1944, 6, 6);
print(dDay.isUtc); // true

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

Use the methods toLocal and toUtc to get the equivalent date/time value specified in the other time zone.

dart
final localDay = dDay.toLocal(); // e.g. 1944-06-06 02:00:00.000
print(localDay.isUtc); // false

final utcFromLocal = localDay.toUtc(); // 1944-06-06 00:00:00.000Z
print(utcFromLocal.isUtc); // true

Use timeZoneName to get an abbreviated name of the time zone for the DateTime object.

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

To find the difference between UTC and the time zone of a DateTime object call timeZoneOffset.

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

Comparing DateTime objects ​

The DateTime class contains methods for comparing DateTimes chronologically, such as isAfter, isBefore, and isAtSameMomentAs.

dart
print(berlinWallFell.isAfter(moonLanding)); // true
print(berlinWallFell.isBefore(moonLanding)); // false
print(dDay.isAtSameMomentAs(localDay)); // true

Using DateTime with Duration ​

Use the add and subtract methods with a Duration object to create a DateTime object based on another. For example, to find the point in time that is 36 hours after now, you can write:

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

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

dart
final difference = berlinWallFell.difference(moonLanding);
print(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.

Implemented types

Available Extensions

Constructors ​

DateTime() ​

DateTime(
  int year, [
  int month = 1,
  int day = 1,
  int hour = 0,
  int minute = 0,
  int second = 0,
  int millisecond = 0,
  int microsecond = 0,
])

Constructs a DateTime instance specified in the local time zone.

For example, to create a DateTime object representing the 7th of September 2017, 5:30pm

dart
final dentistAppointment = DateTime(2017, 9, 7, 17, 30);
Implementation
dart
DateTime(
  int year, [
  int month = 1,
  int day = 1,
  int hour = 0,
  int minute = 0,
  int second = 0,
  int millisecond = 0,
  int microsecond = 0,
]) : this._internal(
       year,
       month,
       day,
       hour,
       minute,
       second,
       millisecond,
       microsecond,
       false,
     );

DateTime.fromMicrosecondsSinceEpoch() ​

DateTime.fromMicrosecondsSinceEpoch(
  int microsecondsSinceEpoch, {
  bool isUtc = false,
})

Constructs a new DateTime instance with the given microsecondsSinceEpoch.

If isUtc is false, then the date is in the local time zone.

The constructed DateTime represents 1970-01-01T00:00:00Z + microsecondsSinceEpoch us in the given time zone (local or UTC).

dart
final newYearsEve =
    DateTime.fromMicrosecondsSinceEpoch(1640979000000000, isUtc:true);
print(newYearsEve); // 2021-12-31 19:30:00.000Z
Implementation
dart
external DateTime.fromMicrosecondsSinceEpoch(
  int microsecondsSinceEpoch, {
  bool isUtc = false,
});

DateTime.fromMillisecondsSinceEpoch() ​

DateTime.fromMillisecondsSinceEpoch(
  int millisecondsSinceEpoch, {
  bool isUtc = false,
})

Constructs a new DateTime instance with the given millisecondsSinceEpoch.

If isUtc is false then the date is in the local time zone.

The constructed DateTime represents 1970-01-01T00:00:00Z + millisecondsSinceEpoch ms in the given time zone (local or UTC).

dart
final newYearsDay =
    DateTime.fromMillisecondsSinceEpoch(1641031200000, isUtc:true);
print(newYearsDay); // 2022-01-01 10:00:00.000Z
Implementation
dart
external DateTime.fromMillisecondsSinceEpoch(
  int millisecondsSinceEpoch, {
  bool isUtc = false,
});

DateTime.now() ​

DateTime.now()

Constructs a DateTime instance with current date and time in the local time zone.

dart
final now = DateTime.now();
Implementation
dart
DateTime.now() : this._now();

DateTime.timestamp() ​

DateTime.timestamp()

Constructs a DateTime with the current UTC date and time.

dart
final mark = DateTime.timestamp();
Implementation
dart
@Since("3.0")
DateTime.timestamp() : this._nowUtc();

DateTime.utc() ​

DateTime.utc(
  int year, [
  int month = 1,
  int day = 1,
  int hour = 0,
  int minute = 0,
  int second = 0,
  int millisecond = 0,
  int microsecond = 0,
])

Constructs a DateTime instance specified in the UTC time zone.

dart
final moonLanding = DateTime.utc(1969, 7, 20, 20, 18, 04);

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

Implementation
dart
DateTime.utc(
  int year, [
  int month = 1,
  int day = 1,
  int hour = 0,
  int minute = 0,
  int second = 0,
  int millisecond = 0,
  int microsecond = 0,
]) : this._internal(
       year,
       month,
       day,
       hour,
       minute,
       second,
       millisecond,
       microsecond,
       true,
     );

Properties ​

day no setter ​

int get day

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

dart
final moonLanding = DateTime.parse('1969-07-20 20:18:04Z');
print(moonLanding.day); // 20
Implementation
dart
external int get day;

hashCode no setter override ​

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Implementation
dart
external int get hashCode;

hour no setter ​

int get hour

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

dart
final moonLanding = DateTime.parse('1969-07-20 20:18:04Z');
print(moonLanding.hour); // 20
Implementation
dart
external int get hour;

isUtc final ​

final bool isUtc

True if this DateTime is set to UTC time.

dart
final dDay = DateTime.utc(1944, 6, 6);
print(dDay.isUtc); // true

final local = DateTime(1944, 6, 6);
print(local.isUtc); // false
Implementation
dart
final bool isUtc;

microsecond no setter ​

int get microsecond

The microsecond [0...999].

dart
final date = DateTime.parse('1970-01-01 05:01:01.234567Z');
print(date.microsecond); // 567
Implementation
dart
external int get microsecond;

microsecondsSinceEpoch no setter ​

int get microsecondsSinceEpoch

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

This value is independent of the time zone.

This value is at most 8,640,000,000,000,000,000us (100,000,000 days) from the Unix epoch. In other words: microsecondsSinceEpoch.abs() <= 8640000000000000000.

Note that this value does not always fit into 53 bits (the size of a IEEE double). On the web JavaScript platforms, there may be a rounding error for DateTime values sufficiently far from the epoch. The year range close to the epoch to avoid rounding is approximately 1685..2254.

Implementation
dart
external int get microsecondsSinceEpoch;

millisecond no setter ​

int get millisecond

The millisecond [0...999].

dart
final date = DateTime.parse('1970-01-01 05:01:01.234567Z');
print(date.millisecond); // 234
Implementation
dart
external int get millisecond;

millisecondsSinceEpoch no setter ​

int get millisecondsSinceEpoch

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

This value is independent of the time zone.

This value is at most 8,640,000,000,000,000ms (100,000,000 days) from the Unix epoch. In other words: millisecondsSinceEpoch.abs() <= 8640000000000000.

Implementation
dart
external int get millisecondsSinceEpoch;

minute no setter ​

int get minute

The minute [0...59].

dart
final moonLanding = DateTime.parse('1969-07-20 20:18:04Z');
print(moonLanding.minute); // 18
Implementation
dart
external int get minute;

month no setter ​

int get month

The month [1..12].

dart
final moonLanding = DateTime.parse('1969-07-20 20:18:04Z');
print(moonLanding.month); // 7
assert(moonLanding.month == DateTime.july);
Implementation
dart
external int get month;

runtimeType no setter inherited ​

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation
dart
external Type get runtimeType;

second no setter ​

int get second

The second [0...59].

dart
final moonLanding = DateTime.parse('1969-07-20 20:18:04Z');
print(moonLanding.second); // 4
Implementation
dart
external int get second;

timeZoneName no setter ​

String get timeZoneName

The time zone name.

This value is provided by the operating system and may be an abbreviation or a full name.

In the browser or on Unix-like systems commonly returns abbreviations, such as "CET" or "CEST". On Windows returns the full name, for example "Pacific Standard Time".

Implementation
dart
external String get timeZoneName;

timeZoneOffset no setter ​

Duration get timeZoneOffset

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

The offset is positive for time zones east of UTC.

Note, that JavaScript, Python and C return the difference between UTC and local time. Java, C# and Ruby return the difference between local time and UTC.

For example, using local time in San Francisco, United States:

dart
final dateUS = DateTime.parse('2021-11-01 20:18:04Z').toLocal();
print(dateUS); // 2021-11-01 13:18:04.000
print(dateUS.timeZoneName); // PDT ( Pacific Daylight Time )
print(dateUS.timeZoneOffset.inHours); // -7
print(dateUS.timeZoneOffset.inMinutes); // -420

For example, using local time in Canberra, Australia:

dart
final dateAus = DateTime.parse('2021-11-01 20:18:04Z').toLocal();
print(dateAus); // 2021-11-02 07:18:04.000
print(dateAus.timeZoneName); // AEDT ( Australian Eastern Daylight Time )
print(dateAus.timeZoneOffset.inHours); // 11
print(dateAus.timeZoneOffset.inMinutes); // 660
Implementation
dart
external Duration get timeZoneOffset;

weekday no setter ​

int get weekday

The day of the week monday..sunday.

In accordance with ISO 8601 a week starts with Monday, which has the value 1.

dart
final moonLanding = DateTime.parse('1969-07-20 20:18:04Z');
print(moonLanding.weekday); // 7
assert(moonLanding.weekday == DateTime.sunday);
Implementation
dart
external int get weekday;

year no setter ​

int get year

The year.

dart
final moonLanding = DateTime.parse('1969-07-20 20:18:04Z');
print(moonLanding.year); // 1969
Implementation
dart
external int get year;

Methods ​

add() ​

DateTime add(Duration duration)

Returns a new DateTime instance with duration added to this DateTime.

dart
final today = DateTime.now();
final fiftyDaysFromNow = today.add(const Duration(days: 50));

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.

Implementation
dart
external DateTime add(Duration duration);

compareTo() override ​

int compareTo(DateTime other)

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

A compareTo function returns:

  • a negative value if this DateTime isBefore other.
  • 0 if this DateTime isAtSameMomentAs other, and
  • a positive value otherwise (when this DateTime isAfter other).
dart
final now = DateTime.now();
final future = now.add(const Duration(days: 2));
final past = now.subtract(const Duration(days: 2));
final newDate = now.toUtc();

print(now.compareTo(future)); // -1
print(now.compareTo(past)); // 1
print(now.compareTo(newDate)); // 0
Implementation
dart
external int compareTo(DateTime other);

copyWith() extension ​

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

Creates a new DateTime from this one by updating individual properties.

The copyWith method creates a new DateTime object with values for the properties DateTime.year, DateTime.hour, etc, provided by similarly named arguments, or using the existing value of the property if no argument, or null, is provided.

Example:

dart
final now = DateTime.now();
final sameTimeOnMoonLandingDay =
    now.copyWith(year: 1969, month: 07, day: 20);

Like for the DateTime and DateTime.utc constructors, which this operation uses to create the new value, property values are allowed to overflow or underflow the range of the property (like a month outside the 1 to 12 range), which can affect the more significant properties (for example, a month of 13 will result in the month of January of the next year.)

Notice also that if the result is a local-time DateTime, seasonal time-zone adjustments (daylight saving) can cause some combinations of dates, hours and minutes to not exist, or to exist more than once. In the former case, a corresponding time in one of the two adjacent time zones is used instead. In the latter, one of the two options is chosen.

Available on DateTime, provided by the DateTimeCopyWith extension

Implementation
dart
DateTime copyWith({
  int? year,
  int? month,
  int? day,
  int? hour,
  int? minute,
  int? second,
  int? millisecond,
  int? microsecond,
  bool? isUtc,
}) {
  return ((isUtc ?? this.isUtc) ? DateTime.utc : DateTime.new)(
    year ?? this.year,
    month ?? this.month,
    day ?? this.day,
    hour ?? this.hour,
    minute ?? this.minute,
    second ?? this.second,
    millisecond ?? this.millisecond,
    microsecond ?? this.microsecond,
  );
}

difference() ​

Duration difference(DateTime other)

Returns a Duration with the difference when subtracting other from this DateTime.

The returned Duration will be negative if other occurs after this DateTime.

dart
final berlinWallFell = DateTime.utc(1989, DateTime.november, 9);
final dDay = DateTime.utc(1944, DateTime.june, 6);

final difference = berlinWallFell.difference(dDay);
print(difference.inDays); // 16592

The difference is measured in seconds and fractions of seconds. The difference above counts the number of fractional seconds between midnight at the beginning of those dates. If the dates above had been in local time, not UTC, then the difference between two midnights may not be a multiple of 24 hours due to daylight saving differences.

For example, in Australia, similar code using local time instead of UTC:

dart
final berlinWallFell = DateTime(1989, DateTime.november, 9);
final dDay = DateTime(1944, DateTime.june, 6);
final difference = berlinWallFell.difference(dDay);
print(difference.inDays); // 16591
assert(difference.inDays == 16592);

will fail because the difference is actually 16591 days and 23 hours, and Duration.inDays only returns the number of whole days.

Implementation
dart
external Duration difference(DateTime other);

isAfter() ​

bool isAfter(DateTime other)

Whether this DateTime occurs after other.

The comparison is independent of whether the time is in UTC or in the local time zone.

dart
final now = DateTime.now();
final later = now.add(const Duration(seconds: 5));
print(later.isAfter(now)); // true
print(!now.isBefore(now)); // true

// This relation stays the same, even when changing timezones.
print(later.isAfter(now.toUtc())); // true
print(later.toUtc().isAfter(now)); // true

print(!now.toUtc().isAfter(now)); // true
print(!now.isAfter(now.toUtc())); // true
Implementation
dart
external bool isAfter(DateTime other);

isAtSameMomentAs() ​

bool isAtSameMomentAs(DateTime other)

Whether this DateTime occurs at the same moment as other.

The comparison is independent of whether the time is in UTC or in the local time zone.

dart
final now = DateTime.now();
final later = now.add(const Duration(seconds: 5));
print(!later.isAtSameMomentAs(now)); // true
print(now.isAtSameMomentAs(now)); // true

// This relation stays the same, even when changing timezones.
print(!later.isAtSameMomentAs(now.toUtc())); // true
print(!later.toUtc().isAtSameMomentAs(now)); // true

print(now.toUtc().isAtSameMomentAs(now)); // true
print(now.isAtSameMomentAs(now.toUtc())); // true
Implementation
dart
external bool isAtSameMomentAs(DateTime other);

isBefore() ​

bool isBefore(DateTime other)

Whether this DateTime occurs before other.

The comparison is independent of whether the time is in UTC or in the local time zone.

dart
final now = DateTime.now();
final earlier = now.subtract(const Duration(seconds: 5));
print(earlier.isBefore(now)); // true
print(!now.isBefore(now)); // true

// This relation stays the same, even when changing timezones.
print(earlier.isBefore(now.toUtc())); // true
print(earlier.toUtc().isBefore(now)); // true

print(!now.toUtc().isBefore(now)); // true
print(!now.isBefore(now.toUtc())); // true
Implementation
dart
external bool isBefore(DateTime other);

noSuchMethod() inherited ​

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dart
dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

dart
class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation
dart
@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

subtract() ​

DateTime subtract(Duration duration)

Returns a new DateTime instance with duration subtracted from this DateTime.

dart
final today = DateTime.now();
final fiftyDaysAgo = today.subtract(const Duration(days: 50));

Notice that the duration being subtracted 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 earlier.

Be careful when working with dates in local time.

Implementation
dart
external DateTime subtract(Duration duration);

toIso8601String() ​

String toIso8601String()

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

The format is yyyy-MM-ddTHH:mm:ss.mmmuuuZ for UTC time, and yyyy-MM-ddTHH:mm:ss.mmmuuu (no trailing "Z") for local/non-UTC time, where:

  • yyyy is a, possibly negative, four digit representation of the year, if the year is in the range -9999 to 9999, otherwise it is a signed six digit representation of the year.
  • MM is the month in the range 01 to 12,
  • dd is the day of the month in the range 01 to 31,
  • HH are hours in the range 00 to 23,
  • mm are minutes in the range 00 to 59,
  • ss are seconds in the range 00 to 59 (no leap seconds),
  • mmm are milliseconds in the range 000 to 999, and
  • uuu are microseconds in the range 001 to 999. If microsecond equals 0, then this part is omitted.

The resulting string can be parsed back using parse.

dart
final moonLanding = DateTime.utc(1969, 7, 20, 20, 18, 04);
final isoDate = moonLanding.toIso8601String();
print(isoDate); // 1969-07-20T20:18:04.000Z
Implementation
dart
String toIso8601String() {
  String y = (year >= -9999 && year <= 9999)
      ? _fourDigits(year)
      : _sixDigits(year);
  String m = _twoDigits(month);
  String d = _twoDigits(day);
  String h = _twoDigits(hour);
  String min = _twoDigits(minute);
  String sec = _twoDigits(second);
  String ms = _threeDigits(millisecond);
  String us = microsecond == 0 ? "" : _threeDigits(microsecond);
  if (isUtc) {
    return "$y-$m-${d}T$h:$min:$sec.$ms${us}Z";
  } else {
    return "$y-$m-${d}T$h:$min:$sec.$ms$us";
  }
}

toLocal() ​

DateTime toLocal()

Returns this DateTime value in the local time zone.

Returns this DateTime if it is already in the local time zone. Otherwise this method is equivalent to:

dart
DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch,
                                    isUtc: false)
Implementation
dart
DateTime toLocal() {
  if (isUtc) {
    return _withUtc(isUtc: false);
  }
  return this;
}

toString() override ​

String toString()

Returns a human-readable string for this instance.

The returned string is constructed for the time zone of this instance. The toString() method provides a simply formatted string. It does not support internationalized strings. Use the intl package at the pub shared packages repo.

The resulting string can be parsed back using parse.

Implementation
dart
String toString() {
  String y = _fourDigits(year);
  String m = _twoDigits(month);
  String d = _twoDigits(day);
  String h = _twoDigits(hour);
  String min = _twoDigits(minute);
  String sec = _twoDigits(second);
  String ms = _threeDigits(millisecond);
  String us = microsecond == 0 ? "" : _threeDigits(microsecond);
  if (isUtc) {
    return "$y-$m-$d $h:$min:$sec.$ms${us}Z";
  } else {
    return "$y-$m-$d $h:$min:$sec.$ms$us";
  }
}

toUtc() ​

DateTime toUtc()

Returns this DateTime value in the UTC time zone.

Returns this DateTime if it is already in UTC. Otherwise this method is equivalent to:

dart
DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch,
                                    isUtc: true)
Implementation
dart
DateTime toUtc() {
  if (isUtc) return this;
  return _withUtc(isUtc: true);
}

Operators ​

operator ==() override ​

bool operator ==(Object other)

Whether other is a DateTime at the same moment and in the same time zone (UTC or local).

dart
final dDayUtc = DateTime.utc(1944, 6, 6);
final dDayLocal = dDayUtc.toLocal();

// These two dates are at the same moment, but are in different zones.
assert(dDayUtc != dDayLocal);
print(dDayUtc != dDayLocal); // true

See isAtSameMomentAs for a comparison that compares moments in time independently of their zones.

Implementation
dart
external bool operator ==(Object other);

Static Methods ​

parse() ​

DateTime parse(String formattedString)

Constructs a new DateTime instance based on formattedString.

Throws a FormatException if the input string cannot be parsed.

The function parses a subset of ISO 8601, which includes the subset accepted by RFC 3339.

The accepted inputs are currently:

  • A date: A signed four-to-six digit year, two digit month and two digit day, optionally separated by - characters. Examples: "19700101", "-0004-12-24", "81030-04-01".
  • An optional time part, separated from the date by either T or a space. The time part is a two digit hour, then optionally a two digit minutes value, then optionally a two digit seconds value, and then optionally a '.' or ',' followed by at least a one digit second fraction. The minutes and seconds may be separated from the previous parts by a ':'. Examples: "12", "12:30:24.124", "12:30:24,124", "123010.50".
  • An optional time-zone offset part, possibly separated from the previous by a space. The time zone is either 'z' or 'Z', or it is a signed two digit hour part and an optional two digit minute part. The sign must be either "+" or "-", and cannot be omitted. The minutes may be separated from the hours by a ':'. Examples: "Z", "-10", "+01:30", "+1130".

This includes the output of both toString and toIso8601String, which will be parsed back into a DateTime object with the same time as the original.

The result is always in either local time or UTC. If a time zone offset other than UTC is specified, the time is converted to the equivalent UTC time.

Examples of accepted strings:

  • "2012-02-27"
  • "2012-02-27 13:27:00"
  • "2012-02-27 13:27:00.123456789z"
  • "2012-02-27 13:27:00,123456789z"
  • "20120227 13:27:00"
  • "20120227T132700"
  • "20120227"
  • "+20120227"
  • "2012-02-27T14Z"
  • "2012-02-27T14+00:00"
  • "-123450101 00:00:00 Z": in the year -12345.
  • "2002-02-27T14:00:00-0500": Same as "2002-02-27T19:00:00Z"

This method accepts out-of-range component values and interprets them as overflows into the next larger component. For example, "2020-01-42" will be parsed as 2020-02-11, because the last valid date in that month is 2020-01-31, so 42 days is interpreted as 31 days of that month plus 11 days into the next month.

To detect and reject invalid component values, use DateFormat.parseStrict from the intl package.

Implementation
dart
static DateTime parse(String formattedString) {
  var re = _parseFormat;
  Match? match = re.firstMatch(formattedString);
  if (match != null) {
    int parseIntOrZero(String? matched) {
      if (matched == null) return 0;
      return int.parse(matched);
    }

    &#47;&#47; Parses fractional second digits of '.(\d+)' into the combined
    &#47;&#47; microseconds. We only use the first 6 digits because of DateTime
    &#47;&#47; precision of 999 milliseconds and 999 microseconds.
    int parseMilliAndMicroseconds(String? matched) {
      if (matched == null) return 0;
      int length = matched.length;
      assert(length >= 1);
      int result = 0;
      for (int i = 0; i < 6; i++) {
        result *= 10;
        if (i < matched.length) {
          result += matched.codeUnitAt(i) ^ 0x30;
        }
      }
      return result;
    }

    int years = int.parse(match[1]!);
    int month = int.parse(match[2]!);
    int day = int.parse(match[3]!);
    int hour = parseIntOrZero(match[4]);
    int minute = parseIntOrZero(match[5]);
    int second = parseIntOrZero(match[6]);
    int milliAndMicroseconds = parseMilliAndMicroseconds(match[7]);
    int millisecond =
        milliAndMicroseconds ~&#47; Duration.microsecondsPerMillisecond;
    int microsecond =
        milliAndMicroseconds.remainder(Duration.microsecondsPerMillisecond)
            as int;
    bool isUtc = false;
    if (match[8] != null) {
      &#47;&#47; timezone part
      isUtc = true;
      String? tzSign = match[9];
      if (tzSign != null) {
        &#47;&#47; timezone other than 'Z' and 'z'.
        int sign = (tzSign == '-') ? -1 : 1;
        int hourDifference = int.parse(match[10]!);
        int minuteDifference = parseIntOrZero(match[11]);
        minuteDifference += 60 * hourDifference;
        minute -= sign * minuteDifference;
      }
    }
    DateTime? result = _finishParse(
      years,
      month,
      day,
      hour,
      minute,
      second,
      millisecond,
      microsecond,
      isUtc,
    );
    if (result == null) {
      throw FormatException("Time out of range", formattedString);
    }
    return result;
  } else {
    throw FormatException("Invalid date format", formattedString);
  }
}

tryParse() ​

DateTime? tryParse(String formattedString)

Constructs a new DateTime instance based on formattedString.

Works like parse except that this function returns null where parse would throw a FormatException.

Implementation
dart
static DateTime? tryParse(String formattedString) {
  &#47;&#47; TODO: Optimize to avoid throwing.
  try {
    return parse(formattedString);
  } on FormatException {
    return null;
  }
}

Constants ​

april ​

const int april
Implementation
dart
static const int april = 4;

august ​

const int august
Implementation
dart
static const int august = 8;

daysPerWeek ​

const int daysPerWeek
Implementation
dart
static const int daysPerWeek = 7;

december ​

const int december
Implementation
dart
static const int december = 12;

february ​

const int february
Implementation
dart
static const int february = 2;

friday ​

const int friday
Implementation
dart
static const int friday = 5;

january ​

const int january
Implementation
dart
static const int january = 1;

july ​

const int july
Implementation
dart
static const int july = 7;

june ​

const int june
Implementation
dart
static const int june = 6;

march ​

const int march
Implementation
dart
static const int march = 3;

may ​

const int may
Implementation
dart
static const int may = 5;

monday ​

const int monday
Implementation
dart
static const int monday = 1;

monthsPerYear ​

const int monthsPerYear
Implementation
dart
static const int monthsPerYear = 12;

november ​

const int november
Implementation
dart
static const int november = 11;

october ​

const int october
Implementation
dart
static const int october = 10;

saturday ​

const int saturday
Implementation
dart
static const int saturday = 6;

september ​

const int september
Implementation
dart
static const int september = 9;

sunday ​

const int sunday
Implementation
dart
static const int sunday = 7;

thursday ​

const int thursday
Implementation
dart
static const int thursday = 4;

tuesday ​

const int tuesday
Implementation
dart
static const int tuesday = 2;

wednesday ​

const int wednesday
Implementation
dart
static const int wednesday = 3;