between

Calendar math differences

Description

example

dt = between(t1,t2) returns the differences between the datetime values in t1 and t2. The dt output is a calendarDuration array in terms of the calendar components years, months, days, and time, such that t2 = t1+dt.

example

dt = between(t1,t2,components) returns the differences between datetime values in terms of the specified calendar or time components.

Examples

collapse all

Create two datetime arrays.

t1 = datetime('now')
t1 = datetime
   26-Aug-2019 11:10:24

t2 = datetime('tomorrow','Format','dd-MMM-yyyy HH:mm:ss') + caldays(0:2)
t2 = 1x3 datetime array
   27-Aug-2019 00:00:00   28-Aug-2019 00:00:00   29-Aug-2019 00:00:00

Find the difference between the two arrays.

dt = between(t1,t2)
dt = 1x3 calendarDuration array
      12h 49m 35.835s   1d 12h 49m 35.835s   2d 12h 49m 35.835s

between returns a calendarDuration array containing differences in terms of days, hours, minutes, and seconds.

Create a sequence of datetimes over a 6-month period. Then, find the number of days between the first date and each of the dates in the sequence.

t1 = datetime(2013,1,1);
t2 = dateshift(t1,'end','month',0:4)
t2 = 1x5 datetime array
   31-Jan-2013   28-Feb-2013   31-Mar-2013   30-Apr-2013   31-May-2013

dt = between(t1,t2,'Days')
dt = 1x5 calendarDuration array
    30d    58d    89d   119d   150d

Input Arguments

collapse all

Input date and time, specified as a datetime array, character vector, cell array of character vectors, or string array. At least one of inputs t1 and t2 must be a datetime array. t1 and t2 must be the same size unless one is a scalar.

Input date and time, specified as a datetime array, character vector, cell array of character vectors, or string array. At least one of inputs t1 and t2 must be a datetime array. t1 and t2 must be the same size unless one is a scalar.

Calendar or time components, specified as one of the following character vectors, or a cell array or string array containing one or more of these values:

  • 'years'

  • 'quarters'

  • 'months'

  • 'weeks'

  • 'days'

  • 'time'

Except for 'time', the above components are flexible lengths of time. For example, one month represents a different length of time when added to a datetime in January than when added to a datetime in February.

between operates on the calendar or time components in decreasing order, starting with the largest component.

In general, t2 is not equal to t1 + dt, unless you include 'time' in components.

Example: {'years','quarters'}

Data Types: char | cell | string

Output Arguments

collapse all

Difference array, returned as a calendarDuration array.

Tips

  • To compute differences between datetime values in t1 and t2 as exact, fixed-length durations, use t2-t1.

Extended Capabilities

Introduced in R2014b