Representing Dates and Times

Why MATLAB Has Special Types for Dates and Times

When you work with measurements, logs, financial data, or any information that changes over time, you quickly run into calendar and clock problems. Months have different lengths, there are leap years, local times and time zones, and shifts such as daylight saving time. Working with raw numbers like 20251229 or text like "29-12-2025" becomes confusing and error prone.

MATLAB provides dedicated data types to represent dates and times in a consistent way, so that you can store them, display them in different formats, and later perform time calculations and plotting in a reliable manner. In this chapter the focus is only on how MATLAB represents dates and times, not on how to create, format, or calculate with them, which will appear in later chapters.

The `datetime` Type

The main type for calendar dates and times in MATLAB is datetime. A datetime value represents a point on the calendar, such as 29 December 2025 at 15:30.

When you look at a datetime value in the Command Window, MATLAB typically shows a human readable representation with a date and optionally a time, for example:

t = datetime(2025,12,29,15,30,0)

might display something like

t = 
  datetime
   29-Dec-2025 15:30:00

This display is a formatting choice. Internally, MATLAB stores datetime values as precise numeric offsets from a reference time, usually in units of days or fractions of a day. You do not normally work with this internal numeric representation directly, but it is useful to know that a datetime is not just text. It also carries metadata such as time zone and display format.

A single datetime value is a scalar. You can also have arrays of datetime values, just like you have arrays of numbers. For example, a vector of measurement times or a table column of event dates is typically stored as a datetime array.

Calendar vs Clock Components

Conceptually, a datetime value combines a calendar part and a clock part. The calendar part consists of year, month, and day, and the clock part consists of hour, minute, and second.

You can think of a generic datetime value as

$$
\text{datetime} = \text{CalendarDate} + \text{TimeOfDay}
$$

For example, 29 December 2025 at 15:30:00 has

Year: 2025, Month: 12, Day: 29

Hour: 15, Minute: 30, Second: 0

In a datetime array, each element has its own combination of these components. MATLAB also allows subsecond resolution, so seconds can include fractional parts, such as 12.345678.

The important point is that all these components live inside a single datetime object. You do not need separate variables for year, month, and so on unless you explicitly want to break them out.

Time Zones and the `TimeZone` Property

Real world times often depend on a time zone. Noon in London is not the same moment as noon in New York. MATLAB datetime objects can be either time zone aware or have no associated time zone.

Every datetime value has a TimeZone property. When TimeZone is an empty string, the datetime is treated as unspecified with respect to time zone. The numeric instant is stored internally, but MATLAB will not perform automatic conversions to or from local times.

When TimeZone is set to a value such as "UTC", "Europe/London", or "America/New_York", the datetime represents an instant in that specific zone. MATLAB can then relate the same moment in time across zones, and it can account for effects like daylight saving time when you later perform conversions or calculations.

Therefore, you can think of a datetime value as having three layers of information:

1. A precise numeric instant from a reference point.
2. A calendar and clock representation for that instant.
3. An optional time zone that defines how the calendar and clock relate to global time.

For many simple uses you may work only with date and time without assigning any time zone. For rigorous work across regions or systems you normally use an explicit time zone.

Representing Only Dates with `datetime`

Sometimes you care only about the date and not about the time of day. For example, for birthdays, settlement dates, or daily summaries, only the calendar date matters.

In MATLAB, you can still use datetime for this purpose. In such cases the time part is usually displayed as midnight, and it is common to use a display format that hides the time. The internal representation still includes a full timestamp, but the time of day is typically zero.

Conceptually, this is still a full datetime value. The only difference is that you do not pay attention to the clock part. This approach keeps your data compatible with other date and time functionality that expects datetime arrays.

Representing Only Times of Day with `duration`

There is another type that represents lengths of time or times of day without a calendar date. This type is called duration. A duration value is purely a quantity of time. It could represent a time interval such as 3.5 hours, or a clock time like 15:30 without linking it to a particular date.

Internally, a duration is stored as a numeric number of seconds, with high precision. You can think of a duration as

$$
\text{duration} = \text{TotalSeconds}
$$

plus formatting rules that decide whether to show hours, minutes, and seconds.

If you want to represent pure elapsed times, such as how long an experiment ran, or lap times in a race, you normally use duration. If you want to represent specific moments on a calendar, such as 29 December 2025 at 15:30, you use datetime.

Representing Calendar Values as Whole Numbers with `calendarduration`

A third type, called calendarduration, represents durations in calendar units such as years, months, and days. This is different from duration, which is based on fixed seconds. A month is not a fixed number of seconds, because months have unequal lengths.

A calendarduration can store components like number of years, number of months, and number of days. For example, a term like 1 year and 6 months is naturally represented as a calendarduration rather than as a duration in seconds.

Conceptually, a calendarduration has components such as

$$
\text{calendarduration} = (\text{years}, \text{months}, \text{days}, \text{time})
$$

and these components are interpreted relative to specific calendar dates when you later add them to datetime values. This matters in situations where adding one month to January 15 is supposed to lead to February 15, regardless of how many seconds that contains.

You typically use calendarduration when your business logic is expressed in terms of calendar units instead of plain seconds, such as payment every 3 months or a contract lasting 2 years.

Arrays of Date and Time Values

All three date and time related types, datetime, duration, and calendarduration, support scalar values and arrays in the same way that numeric types do.

You can have row vectors, column vectors, matrices, and higher dimensional arrays of these types. For example, a column vector of datetime values can represent measurement times for a sensor, while a matching column vector of duration values can represent elapsed times since the start of an experiment.

When you look at these arrays in the Workspace or the Command Window, MATLAB shows them using formatted text values, one per array element, even though it stores them internally as specialized numeric values with associated properties.

Because they are proper array types, you can index into them, slice them, and place them inside tables and other containers, just like with numeric arrays.

Storing Dates and Times as Text and Numbers

Before MATLAB had dedicated date and time types, dates and times were often stored as text (character arrays or strings) or as numeric values representing days from some reference date. You may still encounter such representations when importing data from files.

Examples of common text representations are "2025-12-29", "12/29/2025", or "29-Dec-2025 15:30:00". Similarly, you may see numeric serial date numbers such as 738825.5 that encode a calendar date plus fraction of a day.

For new code, you normally convert such text or serial numbers to datetime, duration, or calendarduration as early as possible, and then work with the specialized types. The details of conversion, parsing formats, and display formats will be covered elsewhere. Here, it is enough to recognize that MATLAB distinguishes between generic text representations of dates and specialized date and time types with well defined behavior.

Date and Time Values in Tables and Timetables

Date and time values are often used as keys or row labels for tabular data. A typical pattern is to store datetime arrays as one of the variables in a table, or to use them as row times in a timetable.

In both cases, the key idea is that individual datetime entries represent unique or repeated time points. The tabular structures themselves are covered elsewhere, so in this chapter the important idea is simply that datetime arrays are the standard way to represent ordered time axes in MATLAB.

Once data are aligned with datetime values, later operations such as time based indexing, resampling, or plotting become straightforward.