description

# DateTime class

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:

    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.

    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:

    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.

    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.

    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.

    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.

    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 `DateTime`s chronologically, such as isAfter, isBefore, and isAtSameMomentAs.

    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:

    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:

    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
  - Comparable<DateTime>
Available extensions
  - DateTimeCopyWith

## Constructors

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.
DateTime.fromMicrosecondsSinceEpoch(int microsecondsSinceEpoch, {bool isUtc = false})
  Constructs a new DateTime instance with the given `microsecondsSinceEpoch`.
DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch, {bool isUtc = false})
  Constructs a new DateTime instance with the given `millisecondsSinceEpoch`.
DateTime.now()
  Constructs a DateTime instance with current date and time in the local time zone.
DateTime.timestamp()
  Constructs a DateTime with the current UTC date and time.
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.

## Properties

day → int
  The day of the month `[1..31]`.
  no setter
hashCode → int
  The hash code for this object.
  no setter override
hour → int
  The hour of the day, expressed as in a 24-hour clock `[0..23]`.
  no setter
isUtc → bool
  True if this DateTime is set to UTC time.
  final
microsecond → int
  The microsecond `[0...999]`.
  no setter
microsecondsSinceEpoch → int
  The number of microseconds since the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
  no setter
millisecond → int
  The millisecond `[0...999]`.
  no setter
millisecondsSinceEpoch → int
  The number of milliseconds since the "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 setter inherited
second → int
  The second `[0...59]`.
  no setter
timeZoneName → String
  The time zone name.
  no setter
timeZoneOffset → Duration
  The time zone offset, which is the difference between local time and UTC.
  no setter
weekday → int
  The day of the week monday..sunday.
  no setter
year → int
  The year.
  no setter

## Methods

add(Duration duration) → DateTime
  Returns a new DateTime instance with `duration` added to this DateTime.
compareTo(DateTime other) → int
  Compares this DateTime object to `other`, 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 on DateTime, provided by the DateTimeCopyWith extension

  Creates a new DateTime from this one by updating individual properties.
difference(DateTime other) → Duration
  Returns a Duration with the difference when subtracting `other` from this DateTime.
isAfter(DateTime other) → bool
  Whether this DateTime occurs after `other`.
isAtSameMomentAs(DateTime other) → bool
  Whether this DateTime occurs at the same moment as `other`.
isBefore(DateTime other) → bool
  Whether this DateTime occurs before `other`.
noSuchMethod(Invocation invocation) → dynamic
  Invoked when a nonexistent method or property is accessed.
  inherited
subtract(Duration duration) → DateTime
  Returns a new DateTime instance with `duration` subtracted from this DateTime.
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 ==(Object other) → bool
  Whether `other` is a DateTime at the same moment and in the same time zone (UTC or local).
  override

## Static Methods

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

## Constants

april → const int
august → const int
daysPerWeek → const int
december → const int
february → const int
friday → const int
january → const int
july → const int
june → const int
march → const int
may → const int
monday → const int
monthsPerYear → const int
november → const int
october → const int
saturday → const int
september → const int
sunday → const int
thursday → const int
tuesday → const int
wednesday → const int