1get_framenum(3) GETDATA get_framenum(3)
2
6 get_framenum_subset, get_framenum — perform a reverse look-up on a
7 monotonic dirfile field
8
10 #include <getdata.h>
11 double get_framenum_subset(DIRFILE *dirfile, const char *field_code,
13 double value, off_t field_start, off_t field_end);
14 double get_framenum(DIRFILE *dirfile, const char *field_code, double
16 value);
17
19 The get_framenum_subset() function queries a dirfile(5) database speci‐
20 fied by dirfile and returns the fractional frame number at which the
21 field specified by field_code, which may contain a representation suf‐
22 fix, equals value, by considering the field between the frame limits
23 field_start and field_end.
24 If field_start is zero, the frame offset of the field is used as the
26 lower limit instead (which may, in fact, be zero; see get_frameoff‐
27 set(3)). If field_end is zero, the number of frames in the dirfile, as
28 reported by get_nframes(3), is used instead as the upper limit.
29 The get_framenum() function is equivalent to calling get_framenum_sub‐
31 set() with field_start and field_end equal to zero.
32 The field must be monotonic (either increasing or decreasing) between
34 the supplied limits. It is not required to be strictly monotonic.
35 If the value searched for lies between two sample values, the frame
37 number returned will be calculated by linear interpolation of the field
38 between these two samples. If more than one consecutive sample is
39 equal to the value searched for, the fractional frame number of one of
40 these samples will be returned, without specifying which particular one
41 will be used.
42 If the value searched for is found to lie outside of the supplied lim‐
44 its, the first two or last two samples of the field will be used to
45 linearly extrapolate the returned frame number. If these two samples
46 happen to have the same value, positive or negative infinity will be
47 returned. When extrapolating, this function will never consider data
48 outside the supplied limits, even if such data exists. As a result,
49 the extrapolated value may differ greatly from the value considering
50 all the data.
51 All computation is done in double precision. As a result, using this
53 function on a 64-bit integer field with more precision than a double
54 precision floating point number, may result in an inaccurate returned
55 value. Attempting to use this function on a complex valued field will
56 result in an error.
57 If the field is constant across the entire range, and error results,
59 even if the value to search for is equal to the constant value of the
60 field.
61
64 On success, these functions return the fractional frame number at which
65 the given function would attain the supplied value, based only on that
66 portion of the field between the given limits. This might be any num‐
67 ber, even values outside of the supplied limits, up to and including
68 positive or negaitve infinity.
69 On error, these functions return an IEEE-754 conforming not-a-number
71 (NaN), and set the dirfile error to a non-zero error value. Possible
72 error values are:
73 GD_E_ALLOC
75 The library was unable to allocate memory.
76 GD_E_BAD_CODE
78 The field specified by field_code was not found.
79 GD_E_BAD_DIRFILE
81 The supplied dirfile was invalid.
82 GD_E_BAD_FIELD_TYPE
84 The field specified by field_code was not a vector field.
85 GD_E_BAD_REPR
87 The representation suffix specified in field_code, or in one of
88 its input fields, was not recognised.
89 GD_E_BAD_SCALAR
91 A scalar field used in the definition of the field was not
92 found, or was not of scalar type.
93 GD_E_DIMENSION
95 A scalar field was found where a vector field was expected.
96 GD_E_DOMAIN
98 The specified field was complex valued, or the supplied frame
99 range was too small. This error may also arise if data is
100 deleted from the field as the function is executing.
101 GD_E_INTERNAL_ERROR
103 An internal error occurred in the library while trying to per‐
104 form the task. This indicates a bug in the library. Please
105 report the incident to the maintainer.
106 GD_E_OPEN_LINFILE
108 An error occurred while trying to read a LINTERP table from
109 disk.
110 GD_E_RANGE
112 The specified field is constant across the specified range.
113 GD_E_RAW_IO
115 An error occurred while trying to open or read from a file on
116 disk containing a raw field.
117 GD_E_RECURSE_LEVEL
119 Too many levels of recursion were encountered while trying to
120 resolve field_code. This usually indicates a circular depen‐
121 dency in field specification in the dirfile.
122 GD_E_UNKNOWN_ENCODING
124 The encoding scheme of a RAW field could not be determined.
125 This may also indicate that the binary file associated with the
126 RAW field could not be found.
127 GD_E_UNSUPPORTED
129 Reading from dirfiles with the encoding scheme of the specified
130 dirfile is not supported by the library. See dirfile-encod‐
131 ing(5) for details on dirfile encoding schemes.
132 The dirfile error may be retrieved by calling get_error(3). A descrip‐
134 tive error string for the last error encountered can be obtained from a
135 call to get_error_string(3).
136
138 dirfile_open(3), get_error(3), get_error_string(3), get_frameoffset(3),
139 get_nframes(3).
140Version 0.6.0 19 October 2009 get_framenum(3)