between

Arguments

d1

A datetime value or array of datetime values.

d2

A datetime value or array of datetime values. d1 and d2 must have compatible dimensions, or one of them must be scalar.

c

A string specifying the requested calendar unit. Valid values are "Years", "Months", "Days", "Time", and "default". The default value is "default".

b

A calendarDuration containing the difference between d1 and d2.

Description

between(d1,d2) computes the calendar difference between two datetime values.

When the default mode is used, the result is decomposed into calendar years, calendar months, calendar days, and a time component.

The direction of the difference is preserved. If d2 is earlier than d1, the resulting calendarDuration contains negative components.

The decomposition is designed so that adding the result to d1 reconstructs d2: d1 + b == d2

Unit selection

The third input argument selects the unit returned by between.

Examples

Calendar difference

d1 = datetime(2026,1,31);
d2 = datetime(2026,3,31);

res = between(d1,d2)

--> d1 = datetime(2026,1,31);

--> d2 = datetime(2026,3,31);

--> res = between(d1,d2)

res = [calendarDuration]

    2mo

Difference in months

d1 = datetime(2024,1,15);
d2 = datetime(2025,4,15);

res = between(d1,d2,"Months")

--> d1 = datetime(2024,1,15);

--> d2 = datetime(2025,4,15);

--> res = between(d1,d2,"Months")

res = [calendarDuration]

    15mo

Difference in days

d1 = datetime(2026,1,1);
d2 = datetime(2026,2,1);
res = between(d1,d2,"Days")

--> d1 = datetime(2026,1,1);

--> d2 = datetime(2026,2,1);

--> res = between(d1,d2,"Days")

res = [calendarDuration]

    31d

Difference in time

d1 = datetime(2026,1,1,10,30,0);
d2 = datetime(2026,1,1,15,45,0);
res = between(d1,d2,"Time")

--> d1 = datetime(2026,1,1,10,30,0);

--> d2 = datetime(2026,1,1,15,45,0);

--> res = between(d1,d2,"Time")

res = [calendarDuration]

    5h 15m 0s

Negative calendar difference

d1 = datetime(2026,3,30)
d2 = datetime(2026,1,31)
res = between(d1,d2)
d1 + res == d2

--> d1 = datetime(2026,3,30)

    d1 = [datetime]

        2026-03-30

--> d2 = datetime(2026,1,31)

    d2 = [datetime]

        2026-01-31

--> res = between(d1,d2)

    res = [calendarDuration]

        -1mo -28d

--> d1 + res == d2

    ans = 

        T

Leap year

d1 = datetime(2020,2,29)
d2 = datetime(2021,2,28)
res = between(d1,d2)
d1 + res == d2

--> d1 = datetime(2020,2,29)

    d1 = [datetime]

        2020-02-29

--> d2 = datetime(2021,2,28)

    d2 = [datetime]

        2021-02-28

--> res = between(d1,d2)

    res = [calendarDuration]

        1y

--> d1 + res == d2

    ans = 

        T

Scalar expansion

d1 = datetime(2026,1,1)
d2 = [datetime(2026,2,1), datetime(2026,3,1)]
res = between(d1,d2)

--> d1 = datetime(2026,1,1)

    d1 = [datetime]

        2026-01-01

--> d2 = [datetime(2026,2,1), datetime(2026,3,1)]

    d2 = [1x2 datetime]

        2026-02-01   2026-03-01

--> res = between(d1,d2)

    res = [1x2 calendarDuration]

        1mo    2mo

See also

• calendarDuration — create a calendarDuration - duration in days, months and years
• caldays — create a calendarDuration in days
• datetime — create points in time

History