The ts_closest_elem() function

The ts_closest_elem() function returns the first element, or column(s) of an element, that is non-null and closest to the given time stamp.

Syntax

ts_tselem
ts_closest_elem(ts_tsdesc *tdesc, 
       mi_datetime       *tstamp,
       mi_string         *cmp, 
       mi_string         *col_list,
       mi_integer         flags, mi_integer *isNull,
       mi_integer        *off)

tdesc

A time series descriptor returned by ts_open.

tstamp

The time stamp to start searching from.

cmp

A comparison operator. Valid values for cmp are <, <=, =, ==, '>=, and >.

col_list

To search for an element with a particular set of columns non-null, specify a list of column names separated by a vertical bar (|). An error is raised if any of the column names do not exist in the time series sub-rowtype.

To search for a non-null element, set col_list to NULL.

flags

Determines whether hidden elements should be returned. Valid values for the flags parameter are defined in tseries.h. They are:

TS_CLOSEST_NO_FLAGS (no special flags)
TS_CLOSEST_RETNULLS_FLAGS (return hidden elements)

isNull

The isNull parameter must not be NULL. On return, it is set with the null indicator bits found in tseries.h. These are:

0 (element is not hidden and is allocated)
TS_NULL_NOTALLOCED (element has not been written to)
TS_NULL_HIDDEN (element is hidden)

off

If the time series is regular, the offset of the returned element will be returned in the off parameter, if off is not NULL.

Description

The search algorithm that ts_closest_elem uses is as follows:

If cmp is any of <=, =, ==, or >=, the search starts at tstamp.
If cmp is <, the search starts at the first element before tstamp.
If cmp is >, the search starts at the first element after tstamp.

The tstamp and cmp parameters are used to determine where to start the search. The search continues in the direction indicated by cmp until an element is found that qualifies. If no element qualifies, then the return value is NULL.

Important: For irregular time series, values in an irregular element persist until the next element. This means that any of the previous “equals” operations on an irregular time series will look for <= first. If cmp is >= and the <= operations fails, the operation then looks forward for the next element; otherwise, NULL is returned.

Returns

An element that meets the criteria described.