NAME

       gd_framenum_subset, gd_framenum — perform a reverse look-up on a monotonic 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 specified by  dirfile  and
       returns  the fractional frame number at which the field specified by field_code, which may
       contain a representation suffix, 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_frameoffset(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_subset() 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 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.

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 number, 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 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 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_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 perform the task.   This
               indicates a bug in the library.  Please report the incident to the maintainer.

       GD_E_IO An  error  occurred  while trying to open or read from a file on disk containing a
               raw field or LINTERP table.

       GD_E_LUT
               A LINTERP table was malformed.

       GD_E_RANGE
               The specified field is constant between the supplied limits.

       GD_E_RECURSE_LEVEL
               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.

       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-encoding(5) for details on dirfile encoding
               schemes.

       A descriptive error string for the error may be obtained by calling gd_error_string(3).

HISTORY

       The get_framenum() and get_framenum_subset() functions appeared in GetData-0.6.0.

       In GetData-0.7.0, these functions were renamed to gd_framenum() and gd_framenum_subset().

SEE ALSO

       gd_error(3), gd_error_string(3), gd_frameoffset(3), gd_nframes(3), gd_open(3)