The ts_next_valid() function

The ts_next_valid() function returns the nearest entry after a given time stamp.

Syntax

ts_tselem 
ts_next_valid(ts_tsdesc    *tsdesc, 
               mi_datetime  *tstamp, 
               mi_integer   *STATUS, 
               mi_integer   *off)

tsdesc: The time series descriptor returned by ts_open().
tstamp: Points to the time stamp that precedes the element returned.
STATUS: Points to an mi_integer value that is filled in on return. See the discussion of ts_hide_elem() (The ts_hide_elem() function) for a description of STATUS.
off: For regular time series, off points to an mi_integer value that is filled in on return with the offset of the returned element. For irregular time series, off is set to -1. Can be NULL.

Description

For regular time series, this function returns the element at the calendar's earliest valid timepoint following the given time stamp. For irregular time series, it returns the earliest element following the given time stamp.

Tip: The ts_next_valid() function is less efficient than ts_next(), so it is better to iterate through a time series using ts_begin_scan() and ts_next() rather than using ts_first_elem() and ts_next_valid().

The equivalent SQL function is GetNextValid.

Returns

The element following the given time stamp. If no valid element exists or the time series is regular and the next valid interval contains a null element, NULL is returned. The value pointed to by off is either -1 if the time series is irregular or the offset of the element if the time series is regular. The element returned must not be freed by the caller. It is overwritten after two fetch calls.

See The ts_hide_elem() function for an explanation of STATUS.