gd_framenum_subset, gd_framenum — perform a reverse look-up on a
monotonic dirfile field
gd_framenum_subset(DIRFILE *dirfile, const char
*field_code, double value, off_t
field_start, off_t field_end);
gd_framenum(DIRFILE *dirfile, const char
*field_code, double value);
() function queries a dirfile(5) database specified
and returns the fractional frame number at which the field
specified by field_code
, which may contain a representation suffix,
, by considering the field between the frame limits
is zero, the frame offset of the field is used as the
lower limit instead (which may, in fact, be zero; see
(3)). If field_end
is zero, the number of frames
in the dirfile, as reported by gd_nframes
(3), is used instead as the
() function is equivalent to calling
() with field_start
The field must be monotonic (either increasing or decreasing) between the
supplied limits. It is not required to be strictly monotonic.
If the value searched for lies between two sample values, the frame number
returned will be calculated by linear interpolation of the field between these
two samples. If more than one consecutive sample is equal to the value
searched for, the fractional frame number of one of these samples will be
returned, without specifying which particular one will be used.
If the value searched for is found to lie outside of the supplied limits, the
first two or last two samples of the field will be used to linearly
extrapolate the returned frame number. If these two samples happen to have the
same value, positive or negative infinity will be returned. When
extrapolating, this function will never consider data outside the supplied
limits, even if such data exists. As a result, the extrapolated value may
differ greatly from the value considering all the data.
All computation is done in double precision. As a result, using this function on
a 64-bit integer field with more precision than a double precision floating
point number, may result in an inaccurate returned value. Attempting to use
this function on a complex valued field will result in an error.
If the field is constant across the entire range, an error results, even if the
value to search for is equal to the constant value of the field.
On success, these functions return the fractional frame number at which the
given function would attain the supplied value, based only on that portion of
the field between the given limits. This might be any number, even values
outside of the supplied limits, up to and including positive or negative
On error, these functions return an IEEE-754 conforming not-a-number (NaN), and
store a negative-valued error code in the DIRFILE
object which may be
retrieved by a subsequent call to gd_error
(3). Possible error codes
- The library was unable to allocate memory.
- The field specified by field_code was not
- The supplied dirfile was invalid.
- A scalar field used in the definition of the field was not
found, or was not of scalar type.
- The field specified by field_code was not a vector
field. Or, a scalar field was found where a vector field was expected in
the definition of the field or one of its inputs.
- The specified field was complex valued, or the supplied
frame range was too small. This error may also arise if data is deleted
from the field as the function is executing.
- An internal error occurred in the library while trying to
perform the task. This indicates a bug in the library. Please report the
incident to the maintainer.
- An error occurred while trying to open or read from a file
on disk containing a raw field or LINTERP table.
- A LINTERP table was malformed.
- The specified field is constant between the supplied
- Too many levels of recursion were encountered while trying
to resolve field_code. This usually indicates a circular dependency
in field specification in the dirfile.
- The encoding scheme of a RAW field could not be determined.
This may also indicate that the binary file associated with the RAW field
could not be found.
- Reading from dirfiles with the encoding scheme of the
specified dirfile is not supported by the library. See dirfile-encoding(5)
for details on dirfile encoding schemes.
A descriptive error string for the error may be obtained by calling
() and get_framenum_subset
() functions appeared in
In GetData-0.7.0, these functions were renamed to gd_framenum