Represent Dates and Times in MATLAB

The primary way to store date and time information is in datetime arrays, which support arithmetic, sorting, comparisons, plotting, and formatted display. The results of arithmetic differences are returned in duration arrays or, when you use calendar-based functions, in calendarDuration arrays.

For example, create a datetime array that represents two dates: June 28, 2025 at 6 a.m. and June 28, 2025 at 7 a.m. Specify numeric values for the year, month, day, hour, minute, and second components for the datetime values.

t = datetime(2014,6,28,6:7,0,0)

t = 1×2 datetime
   28-Jun-2014 06:00:00   28-Jun-2014 07:00:00

You can change the value of a date or time component by assigning new values to the properties of the datetime array. For example, change the day number of each value by assigning new values to the Day property.

t.Day = 27:28

t = 1×2 datetime
   27-Jun-2014 06:00:00   28-Jun-2014 07:00:00

Change the display format of the array by changing its Format property. For example, specify a format that expresses dates and times in ISO 8601 format (including digits for milliseconds). The values in the datetime array do not change when you change the display format.

t.Format = "yyyy-MM-dd HH:mm:ss.SSS"

t = 1×2 datetime
   2014-06-27 06:00:00.000   2014-06-28 07:00:00.000

If you subtract one datetime array from another, the result is a duration array. The values in a duration array represent lengths of times in units of fixed-length, 24-hour days. That is, a duration value of 1 equals one day. The default display format for duration arrays is hh:mm:ss, meaning that a duration value that is one day long displays as 24:00:00.

t2 = datetime(2014,6,28,6:7,0:1,0)

t2 = 1×2 datetime
   28-Jun-2014 06:00:00   28-Jun-2014 07:01:00

d = t2 - t

d = 1×2 duration
   24:00:00   00:01:00

You can change the display format of a duration array by changing its Format property. The lengths of time stay the same, but you can display them using different time units. For example, change the display format to seconds.

d.Format = "s"

d = 1×2 duration
   86400 sec      60 sec

You can create duration arrays for lengths of time in specified time units by using the seconds, minutes, hours, days, or years functions. These functions also set the display format to the matching time unit. For example, create a duration value of 2.5 days, where each day is exactly 24 hours, using the days function. The display format is automatically set to days.

d = days(2.5)

d = duration
   2.5 days

You can also create calendarDuration arrays. Like duration arrays, calendarDuration arrays represent lengths of time. But instead of representing fixed lengths of time, calendarDuration arrays represent time in calendar units of variable length. For example, a calendar month can be 28, 29, 30, or 31 days long, depending on which month is specified. For calculations with datetime arrays that involve calendar days, months, quarters, and years, use calendarDuration arrays.

To create calendarDuration arrays in specified time units, use the caldays, calweeks, calmonths, calquarters, and calyears functions. For example, specify a calendarDuration value of two months.

L = calmonths(2)

L = calendarDuration
   2mo

Add a number of calendar months and calendar days. The number of days remains separate from the number of months because the number of days in a month is not fixed, and cannot be determined until you add the calendarDuration value to a specific datetime array, or subtract it from a datetime array.

L = calmonths(2) + caldays(35)

L = calendarDuration
   2mo 35d

Add calendarDuration to a datetime array to compute new dates and times. The result of the operation is another datetime array, where October 2nd is two months and 35 days later than June 28th.

t3 = t2 + L

t3 = 1×2 datetime
   02-Oct-2014 06:00:00   02-Oct-2014 07:01:00

In summary, there are several ways to represent dates and times, and MATLAB® has a data type for each approach:

• To represent points in time, use the datetime data type. For example, represent Wednesday, June 18, 2014 10:00:00 using datetime with numeric or text inputs.

  • datetime(2014,6,18,10,0,0)

  • datetime("2014-06-18 10:00:00")

• To represent a length of time in units of fixed length, use the duration data type. When using the duration data type, 1 day is always equal to 24 hours, and 1 year is always equal to 365.2425 days. For example, represent 72 hours and 10 minutes using hours and minutes.

  • hours(72) + minutes(10)

• To represent a calendar length of time in units of variable length, use the calendarDuration data type. The calendarDuration data type also accounts for daylight saving time changes and leap years, so that one calendar day might be more or less than 24 hours, and one calendar year can have 365 or 366 days. For example, represent a calendar month using calmonths.

  • calmonths(1)