timetable

Methods

⌂ timetable

Method Reference: timetable.containsrange

timetable: TF = containsrange (tt, ref)
timetable: [TF, whichRows] = containsrange (tt, ref)

True when a timetable spans the whole of a range of times.

TF = containsrange (tt, ref) returns true when every instant of ref lies inside the range of tt, that is between its earliest and its latest row time, both included. The row times need be neither sorted nor unique, since only the two ends of the range are read, and missing row times take no part in it.

ref says what range is meant, in one of three ways. A timerange gives its own bounds, and says at each end whether the bound itself belongs to the range. A timetable gives the range between its earliest and its latest row time, both ends included. A datetime or duration scalar gives a single instant. A reference whose times are of the other kind is refused: elapsed time and a calendar cannot be compared.

[TF, whichRows] = containsrange (…) also returns a column of logicals, one per row of tt, saying which of its rows fall in ref. That answer is the same for all three range predicates and is independent of TF: rows may fall in a range the timetable does not contain.

A timetable whose row times are all missing has no range and answers false, and so does a reference naming no instant, such as a NaT.

See also: overlapsrange, withinrange, timerange, timetable

Source Code: timetable

containsrange asks whether a timetable spans the whole of a range of times. A timetable's range runs from its earliest row time to its latest, so the question is about the two ends and not about the rows in between.

 t0 = datetime (2024, 1, 1);
 Temp = [17.2; 18.9; 21.4; 22.0; 20.1; 18.3];
 Site = categorical ({'N'; 'N'; 'S'; 'S'; 'N'; 'S'});
 TT = timetable (Temp, Site, 'RowTimes', t0 + hours (0:5)')
TT =
  6x2 timetable

            Time            Temp    Site    
    ____________________    ____    ____    

    01-Jan-2024 00:00:00    17.2       N    
    01-Jan-2024 01:00:00    18.9       N    
    01-Jan-2024 02:00:00    21.4       S    
    01-Jan-2024 03:00:00      22       S    
    01-Jan-2024 04:00:00    20.1       N    
    01-Jan-2024 05:00:00    18.3       S
 containsrange (TT, timerange (t0 + hours (1), t0 + hours (3)))
ans = 1

A range reaching past the last reading is not one the timetable spans.

 containsrange (TT, timerange (t0 + hours (3), t0 + hours (8)))
ans = 0

The second output says which rows fell inside the range. It answers a different question from the first: an instant between two readings lies in the timetable's range while belonging to no row of it.

 t0 = datetime (2024, 1, 1);
 TT = timetable ([17.2; 18.9; 21.4], 'RowTimes', t0 + hours (0:2)', ...
                 'VariableNames', {'Temp'});
 [tf, whichRows] = containsrange (TT, t0 + minutes (90))
tf = 1
whichRows =

  0
  0
  0

Another timetable may stand for the range, in which case it is the range between that one's earliest and latest row times, both ends included.

 t0 = datetime (2024, 1, 1);
 Wide = timetable ((1:12)', 'RowTimes', t0 + hours (0:11)');
 Narrow = timetable ((1:4)', 'RowTimes', t0 + hours (2:5)');
 containsrange (Wide, Narrow)
ans = 1
 containsrange (Narrow, Wide)
ans = 0