gd_framenum_subset(3) GETDATA gd_framenum_subset(3)NAME
gd_framenum_subset, gd_framenum — perform a reverse look-up on a mono‐
tonic dirfile field
SYNOPSIS
#include <getdata.h>
double gd_framenum_subset(DIRFILE *dirfile, const char *field_code,
double value, off_t field_start, off_t field_end);
double gd_framenum(DIRFILE *dirfile, const char *field_code, double
value);
DESCRIPTION
The gd_framenum_subset() function queries a dirfile(5) database speci‐
fied by dirfile and returns the fractional frame number at which the
field specified by field_code, which may contain a representation suf‐
fix, equals value, by considering the field between the frame limits
field_start and field_end.
If field_start is zero, the frame offset of the field is used as the
lower limit instead (which may, in fact, be zero; see gd_frameoff‐
set(3)). If field_end is zero, the number of frames in the dirfile, as
reported by gd_nframes(3), is used instead as the upper limit.
The gd_framenum() function is equivalent to calling gd_framenum_sub‐
set() with field_start and field_end equal to zero.
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 lim‐
its, 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.
RETURN VALUE
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 num‐
ber, even values outside of the supplied limits, up to and including
positive or negative infinity.
On error, these functions return an IEEE-754 conforming not-a-number
(NaN), and set the dirfile error to a non-zero error value. Possible
error values are:
GD_E_ALLOC
The library was unable to allocate memory.
GD_E_BAD_CODE
The field specified by field_code was not found.
GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
GD_E_BAD_REPR
The representation suffix specified in field_code, or in one of
its input fields, was not recognised.
GD_E_BAD_SCALAR
A scalar field used in the definition of the field was not
found, or was not of scalar type.
GD_E_DIMENSION
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.
GD_E_DOMAIN
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.
GD_E_INTERNAL_ERROR
An internal error occurred in the library while trying to per‐
form the task. This indicates a bug in the library. Please
report the incident to the maintainer.
GD_E_OPEN_LINFILE
An error occurred while trying to read a LINTERP table from
disk.
GD_E_RANGE
The specified field is constant between the supplied limits.
GD_E_RAW_IO
An error occurred while trying to open or read from a file on
disk containing a raw field.
GD_E_RECURSE_LEVEL
Too many levels of recursion were encountered while trying to
resolve field_code. This usually indicates a circular depen‐
dency in field specification in the dirfile.
GD_E_UNKNOWN_ENCODING
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.
GD_E_UNSUPPORTED
Reading from dirfiles with the encoding scheme of the specified
dirfile is not supported by the library. See dirfile-encod‐
ing(5) for details on dirfile encoding schemes.
The dirfile error may be retrieved by calling gd_error(3). A descrip‐
tive error string for the last error encountered can be obtained from a
call to gd_error_string(3).
SEE ALSOgd_open(3), gd_error(3), gd_error_string(3), gd_frameoffset(3),
gd_nframes(3)Version 0.8.0 18 August 2011 gd_framenum_subset(3)
