Dates and Time

Arrays of date and time values that can be displayed in different formats

The date and time data types datetime, duration, and calendarDuration support efficient computations, comparisons, and formatted display of dates and times. Work with these arrays in the same way that you work with numeric arrays. You can add, subtract, sort, compare, concatenate, and plot date and time values. You also can represent dates and times as numeric arrays or as text. For more information, see Represent Dates and Times in MATLAB or watch Date and Time Arrays.

Functions

expand all

Create Date and Time Arrays

Points in Time

`datetime`	Arrays that represent points in time
`dateshift`	Shift date or generate sequence of dates and times
`NaT`	Not-a-Time
`eomday`	Last day of month
`lweekdate`	(Not recommended; use `dateshift`) Date of last occurrence of weekday in month
`nweekdate`	(Not recommended; use `dateshift`) Date of specific occurrence of weekday in month

Durations

`years`	Duration in years
`days`	Duration in days
`hours`	Duration in hours
`minutes`	Duration in minutes
`seconds`	Duration in seconds
`milliseconds`	Duration in milliseconds
`duration`	Lengths of time in fixed-length units

Calendar Durations

`calyears`	Calendar duration in years
`calquarters`	Calendar duration in quarters
`calmonths`	Calendar duration in months
`calweeks`	Calendar duration in weeks
`caldays`	Calendar duration in days
`calendarDuration`	Lengths of time in variable-length calendar units

Calendar of Month

calendar Calendar for specified month

Points in Time in Alternate Formats

`datenum`	(Not recommended; use `datetime` or `duration`) Convert date and time to serial date number
`now`	(Not recommended; use `datetime`) Current date and time as serial date number
`clock`	(Not recommended; use `datetime`) Current date and time as date vector
`date`	(Not recommended; use `datetime("today")`) Current date as character vector
`today`	(Not recommended; use `datetime("today")`) Current date
`eomdate`	(Not recommended; use `dateshift`) Last date of month

Date and Time Components

Extract Components

`year`	Year number of input date and time
`quarter`	Quarter number of input date and time
`month`	Month number or name of input date and time
`week`	Week number of input date and time
`day`	Day number or name of input date and time
`weekday`	Day of week
`hour`	Hour component of input date and time
`minute`	Minute component of input date and time
`second`	Seconds component of input date and time
`weeknum`	(Not recommended; use `week`) Week in year

Split into Components

`ymd`	Year, month, and day numbers of datetime
`hms`	Hour, minute, and second numbers of datetime or duration
`datevec`	Convert date and time to vector of components
`split`	Split calendar duration into numeric and duration units
`time`	Convert time of calendar duration to duration
`timeofday`	Elapsed time since midnight for `datetime` arrays

Calculate Differences or Shift Dates

`datetime` Arrays

`between`	Calendar math differences
`caldiff`	Calendar math successive differences
`tzoffset`	Time zone offset from UTC
`dateshift`	Shift date or generate sequence of dates and times

Fixed-Format Arrays

`addtodate`	(Not recommended; use `duration` or `calendarDuration`) Add time to serial date number
`etime`	(Not recommended; use `datetime` values or `between`) Time elapsed between date vectors
`months`	(Not recommended; use `between`) Number of whole months between dates

Query Array Contents

`isbetween`	Determine which elements are within specified range
`isregular`	Determine if input times are regular with respect to time or calendar unit
`isnat`	Determine NaT (Not-a-Time) elements
`isdst`	Determine daylight saving time elements
`isweekend`	Determine weekend elements
`isdatetime`	Determine if input is datetime array
`isduration`	Determine if input is duration array
`iscalendarduration`	Determine if input is calendar duration array

Convert to Text

`string`	String array
`char`	Character array
`datestr`	(Not recommended; use `string` or `char`) Convert date and time to string format

Excel, POSIX, and Other Date and Time Systems

Conversions

`convertTo`	Convert `datetime` values to numeric representations
`exceltime`	Convert MATLAB datetime to Excel date number
`posixtime`	Convert MATLAB datetime to POSIX time
`juliandate`	Convert MATLAB datetime to Julian date
`yyyymmdd`	Convert MATLAB datetime to YYYYMMDD numeric value
`m2xdate`	(Not recommended; use `exceltime`) MATLAB date to Excel serial date number
`x2mdate`	(Not recommended; use `datetime`) Excel serial date number to MATLAB serial date number or `datetime` value

Times in MATLAB

`timezones`	List all time zones
`leapseconds`	List all leap seconds supported by `datetime` data type (Since R2020a)

Backward Compatibility

matlab.datetime.compatibility.convertDatenum Convert inputs to datetime values in a backward-compatible way (Since R2022a)

Topics

Represent Dates and Times in MATLAB

Use datetime arrays to store date and time information. These arrays support arithmetic, sorting, comparisons, plotting, and formatted display.
Replace Discouraged Instances of Serial Date Numbers and Date Strings
As of R2022b, serial date numbers and date strings are not recommended for specifying dates and times. Use the datetime, duration, and calendarDuration data types instead. Follow these recommendations for updating your code.
Compare Dates and Time

Compare dates, times, and durations by using relational operators, such as >, <, and ==, taking time zones and daylight saving time into account.
- Date and Time Arithmetic
- Plot Dates and Times
Set Date and Time Display Format
The Format property on datetime, duration, and calendarDuration arrays controls the display of values in each array. You can change the value of this property. Changing the Format property does not change the values in the array, only their display.
Specify Time Zones

Specify time zones for datetime arrays to account for time zone offsets, daylight saving time, or leap seconds.
- Convert Date and Time to Julian Date or POSIX Time
Share Code and Data Across Locales
Follow these best practices when sharing code that handles dates and time with MATLAB^® users in other locales. Write and read dates from other locales.
Core Functions Supporting Date and Time Arrays
Many functions in MATLAB operate on date and time arrays in much the same way that they operate on other arrays.

Troubleshooting

Carryover in Date Vectors and Strings

If an element falls outside the conventional range, MATLAB adjusts both that date vector element and the previous element.

Converting Date Vector Returns Unexpected Output

Because a date vector is a 1-by-6 vector of numbers, datestr might interpret your input date vectors as vectors of serial date numbers—or interpret serial date numbers as date vectors—and return unexpected output.