1gd_framenum_subset(3) GETDATA gd_framenum_subset(3)
10
14 gd_framenum_subset, gd_framenum — perform a reverse look-up on a mono‐
15 tonic dirfile field
16
19 #include <getdata.h>
20 double gd_framenum_subset(DIRFILE *dirfile, const char *field_code,
22 double value, off_t field_start, off_t field_end);
23 double gd_framenum(DIRFILE *dirfile, const char *field_code, double
25 value);
26
29 The gd_framenum_subset() function queries a dirfile(5) database speci‐
30 fied by dirfile and returns the fractional frame number at which the
31 field specified by field_code, which may contain a representation suf‐
32 fix, equals value, by considering the field between the frame limits
33 field_start and field_end.
34 If field_start is zero, the frame offset of the field is used as the
36 lower limit instead (which may, in fact, be zero; see
37 gd_frameoffset(3)). If field_end is zero, the number of frames in the
38 dirfile, as reported by gd_nframes(3), is used instead as the upper
39 limit.
40 The gd_framenum() function is equivalent to calling
42 gd_framenum_subset() with field_start and field_end equal to zero.
43 The field must be monotonic (either increasing or decreasing) between
45 the supplied limits. It is not required to be strictly monotonic.
46 If the value searched for lies between two sample values, the frame
48 number returned will be calculated by linear interpolation of the field
49 between these two samples. If more than one consecutive sample is
50 equal to the value searched for, the fractional frame number of one of
51 these samples will be returned, without specifying which particular one
52 will be used.
53 If the value searched for is found to lie outside of the supplied lim‐
55 its, the first two or last two samples of the field will be used to
56 linearly extrapolate the returned frame number. If these two samples
57 happen to have the same value, positive or negative infinity will be
58 returned. When extrapolating, this function will never consider data
59 outside the supplied limits, even if such data exists. As a result,
60 the extrapolated value may differ greatly from the value considering
61 all the data.
62 All computation is done in double precision. As a result, using this
64 function on a 64-bit integer field with more precision than a double
65 precision floating point number, may result in an inaccurate returned
66 value. Attempting to use this function on a complex valued field will
67 result in an error.
68 If the field is constant across the entire range, an error results,
70 even if the value to search for is equal to the constant value of the
71 field.
72
75 On success, these functions return the fractional frame number at which
76 the given function would attain the supplied value, based only on that
77 portion of the field between the given limits. This might be any num‐
78 ber, even values outside of the supplied limits, up to and including
79 positive or negative infinity.
80 On error, these functions return an IEEE-754 conforming not-a-number
82 (NaN), and store a negative-valued error code in the DIRFILE object
83 which may be retrieved by a subsequent call to gd_error(3). Possible
84 error codes are:
85 GD_E_ALLOC
87 The library was unable to allocate memory.
88 GD_E_BAD_CODE
90 The field specified by field_code was not found.
91 GD_E_BAD_DIRFILE
93 The supplied dirfile was invalid.
94 GD_E_BAD_SCALAR
96 A scalar field used in the definition of the field was not
97 found, or was not of scalar type.
98 GD_E_DIMENSION
100 The field specified by field_code was not a vector field. Or,
101 a scalar field was found where a vector field was expected in
102 the definition of the field or one of its inputs.
103 GD_E_DOMAIN
105 The specified field was complex valued, or the supplied frame
106 range was too small. This error may also arise if data is
107 deleted from the field as the function is executing.
108 GD_E_INTERNAL_ERROR
110 An internal error occurred in the library while trying to per‐
111 form the task. This indicates a bug in the library. Please
112 report the incident to the maintainer.
113 GD_E_IO An error occurred while trying to open or read from a file on
115 disk containing a raw field or LINTERP table.
116 GD_E_LUT
118 A LINTERP table was malformed.
119 GD_E_RANGE
121 The specified field is constant between the supplied limits.
122 GD_E_RECURSE_LEVEL
124 Too many levels of recursion were encountered while trying to
125 resolve field_code. This usually indicates a circular depen‐
126 dency in field specification in the dirfile.
127 GD_E_UNKNOWN_ENCODING
129 The encoding scheme of a RAW field could not be determined.
130 This may also indicate that the binary file associated with the
131 RAW field could not be found.
132 GD_E_UNSUPPORTED
134 Reading from dirfiles with the encoding scheme of the specified
135 dirfile is not supported by the library. See dirfile-encod‐
136 ing(5) for details on dirfile encoding schemes.
137 A descriptive error string for the error may be obtained by calling
139 gd_error_string(3).
140
143 The get_framenum() and get_framenum_subset() functions appeared in Get‐
144 Data-0.6.0.
145 In GetData-0.7.0, these functions were renamed to gd_framenum() and
147 gd_framenum_subset().
148
151 gd_error(3), gd_error_string(3), gd_frameoffset(3), gd_nframes(3),
152 gd_open(3)
153Version 0.10.0 25 December 2016 gd_framenum_subset(3)