get_framenum_subset (3) - Linux Man Pages
get_framenum_subset: perform a reverse look-up on a monotonic
NAMEget_framenum_subset, get_framenum --- perform a reverse look-up on a monotonic dirfile field
double get_framenum_subset(DIRFILE *dirfile, const char *field_code,
double value, off_t field_start, off_t field_end);
- double get_framenum(DIRFILE *dirfile, const char *field_code, double value);
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 get_frameoffset(3)). If field_end is zero, the number of frames in the dirfile, as reported by get_nframes(3), is used instead as the upper limit.
The get_framenum() function is equivalent to calling get_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, and error results, even if the value to search for is equal to the constant value of the field.
RETURN VALUEOn 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 negaitve 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:
- The library was unable to allocate memory.
- The field specified by field_code was not found.
- The supplied dirfile was invalid.
- The field specified by field_code was not a vector field.
- The representation suffix specified in field_code, or in one of its input fields, was not recognised.
- A scalar field used in the definition of the field was not found, or was not of scalar type.
- A scalar field was found where a vector field was expected.
- 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 read a LINTERP table from disk.
- The specified field is constant across the specified range.
- An error occurred while trying to open or read from a file on disk containing a raw field.
- 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. The dirfile error may be retrieved by calling get_error(3). A descriptive error string for the last error encountered can be obtained from a call to get_error_string(3).