Datetime class dart core library dart api


DateTime class


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.


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.


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.
    • 

    
  
  • Comparable< DateTime >
    • 

    
  
  • 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] .
hashCode → int The hash code for this object.
read-only override
hour → int The hour of the day, expressed as in a 24-hour clock [0..23] .
isUtc → bool True if this DateTime is set to UTC time.
microsecond → int The microsecond [0. 999] .

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

millisecond → int The millisecond [0. 999] .

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