Compare Dates and Time

Compare datetime Values

Create a datetime array. To convert text representing a date and time, use the datetime function.

d1 = datetime("2022-06-05 11:37:05")

d1 = datetime
   05-Jun-2022 11:37:05

Create another datetime array by converting input numeric arrays that represent datetime components—years, months, days, hours, minutes, and seconds.

d2 = datetime(2022,2:4:10,15,12,0,0)

d2 = 1x3 datetime
   15-Feb-2022 12:00:00   15-Jun-2022 12:00:00   15-Oct-2022 12:00:00

Compare the two datetime arrays. The result shows which elements of d2 occur after d1.

tf = d2 > d1

tf = 1x3 logical array

   0   1   1

To create a datetime array containing only the matching elements, index into d2 using tf.

afterd1 = d2(tf)

afterd1 = 1x2 datetime
   15-Jun-2022 12:00:00   15-Oct-2022 12:00:00

Text and datetime Values

If you have text that represents dates and times in a format that the datetime function recognizes, then you can compare the text to a datetime array. The comparison implicitly converts the text.

For example, compare d2 to a string that represents June 1, 2022. (If the string only specifies a date, then the implicit conversion to datetime sets the time to midnight.) The first element of d2 occurs before June 1.

tf = d2 >= "2022-06-01"

tf = 1x3 logical array

   0   1   1

afterJune1 = d2(tf)

afterJune1 = 1x2 datetime
   15-Jun-2022 12:00:00   15-Oct-2022 12:00:00

Numbers and Components of datetime Arrays

The datetime data type provides access to the components of datetime values. Access components by using the year, quarter, month, day, hour, minute, and second functions. You can compare components to numbers or duration values because these functions return numbers.

For example, display the datetime array d2. Then display its month component.

d2

d2 = 1x3 datetime
   15-Feb-2022 12:00:00   15-Jun-2022 12:00:00   15-Oct-2022 12:00:00

m = month(d2)

m = 1×3

     2     6    10

Another way to access the month component is by using the Month property of d2. You can access datetime components by their Year, Month, Day, Hour, Minute, and Second properties.

m = d2.Month

m = 1×3

     2     6    10

To find the elements of d2 that occur before the month of June, compare d2 to the numeric value corresponding to June. Then index into d2.

tf = month(d2) < 6

tf = 1x3 logical array

   1   0   0

beforeJune = d2(tf)

beforeJune = datetime
   15-Feb-2022 12:00:00

Compare duration Arrays

Create a duration array. To convert text in hh:mm:ss format, use the duration function.

t1 = duration("03:37:12")

t1 = duration
   03:37:12

Create another duration array by converting input numeric arrays that represent hours, minutes, and seconds.

t2 = duration(0:2:6,30,0)

t2 = 1x4 duration
   00:30:00   02:30:00   04:30:00   06:30:00

Compare the two duration arrays. The result show which elements of t2 are longer than t1.

tf = t2 > t1

tf = 1x4 logical array

   0   0   1   1

To create a new duration array containing only the matching elements, index into t2 using tf.

longerThanT1 = t2(tf)

longerThanT1 = 1x2 duration
   04:30:00   06:30:00

Text and duration Values

If you have text that represents a length of time in a format that the duration function recognizes, then you can compare the text to a duration array. The comparison implicitly converts the text.

For example, compare t2 to a string that represents two hours and five minutes. The first element of t2 is shorter.

tf = t2 >= "02:05:00"

tf = 1x4 logical array

   0   1   1   1

longerThan205 = t2(tf)

longerThan205 = 1x3 duration
   02:30:00   04:30:00   06:30:00

Numbers and duration Arrays

You can compare numeric arrays to duration arrays. The comparison treats a numeric value as a number of fixed-length (24-hour) days.

Compare the elements of t2 to one day. Every element is shorter.

tf = t2 < 1

tf = 1x4 logical array

   1   1   1   1

t2(tf)

ans = 1x4 duration
   00:30:00   02:30:00   04:30:00   06:30:00

Compare the elements of t2 to one hour. Only the first element of t2 is shorter.

tf = t2 < 1/24

tf = 1x4 logical array

   1   0   0   0

t2(tf)

ans = duration
   00:30:00

Compare datetime Arrays in Different Time Zones

Create datetime values for October 1, 2022, at 4:00 p.m. in Los Angeles and October 1, 2022 at 5:00 p.m. in New York. The two cities are in different time zones.

You can create datetime arrays with time zones by specifying the TimeZone name-value argument. To show the time zone when displaying these values, specify the Format name-value argument. Note that you can specify a datetime display format that differs from the format of the input text.

LAtime = datetime("2022-10-01 16:00:00", ...
                  "TimeZone","America/Los_Angeles",...
                  "Format","dd-MMM-yyyy hh:mm:ss a z")

LAtime = datetime
   01-Oct-2022 04:00:00 PM PDT

NYtime = datetime("2022-10-01 17:00:00", ...
                  "TimeZone","America/New_York",...
                  "Format","dd-MMM-yyyy hh:mm:ss a z")

NYtime = datetime
   01-Oct-2022 05:00:00 PM EDT

Compare the times in the two cities. On the same day, 4:00 p.m. in Los Angeles occurs after 5:00 p.m. in New York. When you specify time zones, comparisons of datetime arrays account for the time zone information of each array.

tf = NYtime < LAtime

tf = logical
   1

Compare two datetime values with the same clock time using the == operator. The two values are not equal because their time zones are different.

NYtime4 = datetime("2022-10-01 16:00:00", ...
                  "TimeZone","America/New_York",...
                  "Format","dd-MMM-yyyy hh:mm:ss a z")

NYtime4 = datetime
   01-Oct-2022 04:00:00 PM EDT

tf = NYtime4 == LAtime

tf = logical
   0

You cannot compare a datetime array with a time zone to a datetime array without a time zone. If only one datetime array has a time zone, then there is not enough information for a comparison.

Compare Dates and Times Using Other Functions

MATLAB provides other functions for date and time comparisons.

You can also perform set operations on datetime or duration arrays.

For example, determine if any elements of a datetime array occur during the first quarter of 2022. (The end of the first quarter is the same as the first moment of the second quarter.)

start1Q = datetime("2022-01-01");
end1Q = datetime("2022-04-01");
d = datetime(2022,2:4:10,15,12,0,0)

d = 1x3 datetime
   15-Feb-2022 12:00:00   15-Jun-2022 12:00:00   15-Oct-2022 12:00:00

To determine which elements of d are between the start and the end of the first quarter, use isbetween. Specify the time interval between start1Q and end1Q as an open-right interval.

tf = isbetween(d,start1Q,end1Q,"openright")

tf = 1x3 logical array

   1   0   0

When you use isbetween and specify an open-right interval, it is equivalent to this expression. The interval includes the moment at the start of January 1, 2022 and every moment up to, but not including, the start of April 1, 2022. When you specify the end of a time period by using the start of the next time period, consider that time period to be an open-right time interval.

tf = (start1Q <= d & d < end1Q)

tf = 1x3 logical array

   1   0   0

Display the elements of d that occur during the first quarter.

d(tf)

ans = datetime
   15-Feb-2022 12:00:00

Specify the time zone of d by setting its TimeZone property. Then determine if any elements occur during daylight saving time.

d.TimeZone = "America/New_York";
isdst(d)

ans = 1x3 logical array

   0   1   1

Determine if any elements occur during a weekend.

isweekend(d)

ans = 1x3 logical array

   0   0   1

To show the day of the week of the matching elements, use the day function.

weekendDays = d(isweekend(d))

weekendDays = datetime
   15-Oct-2022 12:00:00

day(weekendDays,"name")

ans = 1x1 cell array
    {'Saturday'}