isbetween

Determine elements within date and time interval

Description

example

tf = isbetween(t,tlower,tupper) returns an array containing logical 1 (true) where the corresponding element of t is a datetime or duration value that lies within the closed interval specified by the corresponding elements of tlower and tupper. The output tf indicates which elements of t satisfy:

tlower <= t & t <= tupper

The sizes of t, tlower, and tupper must be the same or be compatible. If the sizes of the input arrays are compatible, then the arrays implicitly expand to match each other. For example, if one of t, tlower, or tupper is a scalar, then the scalar is compared to each element of the other arrays. Also, vectors with different orientations (row vectors and column vectors) implicitly expand to form a matrix.

example

tf = isbetween(t,tlower,tupper,intervalType) determines if elements of t are within the type of interval specified by intervalType. For example, if intervalType is 'open', then isbetween determines which elements of t satisfy tlower < t & t < tupper as a condition.

Examples

collapse all

Specify a lower bound and an upper bound for dates.

tlower = datetime(2021,05,16)
tlower = datetime
16-May-2021

tupper = "2021-05-23"
tupper =
"2021-05-23"

tlower and tupper can be datetime arrays, duration arrays, strings, or character vectors. Here, tlower is a datetime array and tupper is a string scalar.

Create an array of datetime values. You can start with one datetime value, tlower, and add an array of calendar days to it by using the caldays function. The result is an array of datetime values, spaced two days apart.

t = tlower + caldays(2:2:10)
t = 1x5 datetime
18-May-2021   20-May-2021   22-May-2021   24-May-2021   26-May-2021

Determine which datetime values lie within the closed interval bounded by tlower and tupper.

tf = isbetween(t,tlower,tupper)
tf = 1x5 logical array

1   1   1   0   0

To display the dates that lie within the interval, index into t using tf as logical indices.

t(tf)
ans = 1x3 datetime
18-May-2021   20-May-2021   22-May-2021

Specify upper and lower bounds for an interval testing duration values using seconds. The seconds function converts the specified number of seconds into a duration array, formatted to display elapsed time in seconds.

tlower = seconds(3)
tlower = duration
3 sec

tupper = seconds(9)
tupper = duration
9 sec

Create an array of duration values.

t = seconds(1:10)
t = 1x10 duration
Columns 1 through 8

1 sec    2 sec    3 sec    4 sec    5 sec    6 sec    7 sec    8 sec

Columns 9 through 10

9 sec   10 sec

Determine which elements of t are within the interval. Then display them.

tf = isbetween(t,tlower,tupper);
t(tf)
ans = 1x7 duration
3 sec   4 sec   5 sec   6 sec   7 sec   8 sec   9 sec

Specify upper and lower bounds for an interval testing dates.

tlower = datetime(2021,5,16)
tlower = datetime
16-May-2021

tupper = datetime(2021,5,23)
tupper = datetime
23-May-2021

Create an array of datetime values, with the first element equal to tlower.

t = tlower + caldays(0:2:8)
t = 1x5 datetime
16-May-2021   18-May-2021   20-May-2021   22-May-2021   24-May-2021

Determine which dates occur within the open interval, tlower < t & t < tupper.

tf = isbetween(t,tlower,tupper,'open')
tf = 1x5 logical array

0   1   1   1   0

To display the dates within the open interval, index into t using tf as logical indices.

t(tf)
ans = 1x3 datetime
18-May-2021   20-May-2021   22-May-2021

Determine which dates occur within the half-open interval, tlower <= t & t < tupper. Display the dates.

tf = isbetween(t,tlower,tupper,'openright');
t(tf)
ans = 1x4 datetime
16-May-2021   18-May-2021   20-May-2021   22-May-2021

Input Arguments

collapse all

Input date and time, specified as a datetime array, duration array, character vector, cell array of character vectors, or string array. Character vectors and strings must be formatted to represent dates and times.

Lower bound of date and time interval, specified as a datetime array, duration array, character vector, cell array of character vectors, or string array. Character vectors and strings must be formatted to represent dates and times.

Upper bound of date and time interval, specified as a datetime array, duration array, character vector, cell array of character vectors, or string array. Character vectors and strings must be formatted to represent dates and times.

Type of time range interval, specified as 'open', 'closed', 'openleft', 'openright', 'closedright', or 'closedleft'. The table describes the types of time range intervals.

Interval Type

Description

'open'

Select values that satisfy the open interval tlower < t and t < tupper.

'closed' (default)

Select values that satisfy the closed interval tlower <= t and t <= tupper.

'openleft'

Select values that satisfy the half-open interval tlower < t and t <= tupper.

'openright' (default)

Select values that satisfy the half-open interval tlower <= t and t < tupper.

'closedright'

Equivalent to 'openleft'.

'closedleft'

Equivalent to 'openright'.

Compatibility Considerations

expand all

Behavior changed in R2020b