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 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_FIELD_TYPE
               The field specified by field_code was not a vector field.

       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
               A scalar field was found where a vector field was expected.

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

       The dirfile error may be retrieved by calling gd_error(3).  A descriptive error string for the last error
       encountered can be obtained from a call to gd_error_string(3).

SEE ALSO

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