between

Calendar math differences

Syntax

dt = between(t1,t2)

dt = between(t1,t2,components)

Description

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.

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

Examples

Differences Between Two Datetime Arrays

Create two datetime arrays.

t1 = datetime('now')

t1 = datetime
   03-Mar-2023 07:46:09

t2 = datetime('tomorrow','Format','dd-MMM-yyyy HH:mm:ss') + caldays(0:2)

t2 = 1x3 datetime
   04-Mar-2023 00:00:00   05-Mar-2023 00:00:00   06-Mar-2023 00:00:00

Find the difference between the two arrays.

dt = between(t1,t2)

dt = 1x3 calendarDuration
      16h 13m 50.413s   1d 16h 13m 50.413s   2d 16h 13m 50.413s

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

Difference Between Datetime Values in Calendar Days

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
   31-Jan-2013   28-Feb-2013   31-Mar-2013   30-Apr-2013   31-May-2013

dt = between(t1,t2,'Days')

dt = 1x5 calendarDuration
    30d    58d    89d   119d   150d

Input Arguments

t1 — Input date and time

datetime array | character vector | cell array of character vectors | string array

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.

t2 — Input date and time

datetime array | character vector | cell array of character vectors | string array

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.

components — Calendar or time components

'years' | 'quarters' | 'months' | 'weeks' | 'days' | 'time' | cell array of character vectors | string array

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

dt — Difference array

calendarDuration array

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

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

This function fully supports tall arrays. For more information, see Tall Arrays.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2014b