between

R2026b

Calendar math differences

Syntax

dt = between(t1,t2)

dt = between(t1,t2,components)

dt = between(t1,t2,components,ArithmeticMethod=arithmeticMethod)

Description

The between function returns the calendar differences between two datetime arrays. When between calculates the calendar difference between two datetime values, it takes into account leap years, Daylight Saving Time shifts, and the differing lengths of calendar months. To calculate differences as exact fixed-length durations, use subtraction instead, as in dt = t2 - t1.

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.

dt = between(t1,t2,components,ArithmeticMethod=arithmeticMethod) sets the arithmetic method of the returned calendar duration dt.

Examples

Differences Between Two Datetime Arrays

Create two datetime arrays.

t1 = datetime('now')

t1 = datetime
   07-Aug-2026 00:42:04

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

t2 = 1×3 datetime
   08-Aug-2026 00:00:00   09-Aug-2026 00:00:00   10-Aug-2026 00:00:00

Find the difference between the two arrays.

dt = between(t1,t2)

dt = 1×3 calendarDuration
      23h 17m 55.356s   1d 23h 17m 55.356s   2d 23h 17m 55.356s

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 = 1×5 datetime
   31-Jan-2013   28-Feb-2013   31-Mar-2013   30-Apr-2013   31-May-2013

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

dt = 1×5 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

arithmeticMethod — Arithmetic method of returned calendar duration

"default" | "endofmonth" | "endofquarter"

Arithmetic method of the returned calendar duration, specified as one of the values in this table.

Value	Description
"default"	The returned calendar duration has ArithmeticMethod set to "default", and preserves the day of the month in datetime arithmetic.
"endofmonth"	The returned calendar duration has ArithmeticMethod set to "endofmonth", and preserves month ends in datetime arithmetic.
"endofquarter"	The returned calendar duration has ArithmeticMethod set to "endofquarter", and preserves quarter ends in datetime arithmetic.

Use ArithmeticMethod="endofmonth" only when components is "months", and use ArithmeticMethod="endofquarter" only when components is "quarters".

Data Types: string | char

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.

The between 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.

The between 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™.

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

Version History

Introduced in R2014b

R2026b: Specify arithmetic method of returned calendar duration

The between function now supports the ArithmeticMethod name-value argument. Use the ArithmeticMethod to specify the arithmetic method of the returned calendar duration.