1
2
3
4
5
6
7
8
9gd_framenum_subset(3)               GETDATA              gd_framenum_subset(3)
10
11
12

NAME

14       gd_framenum_subset,  gd_framenum — perform a reverse look-up on a mono‐
15       tonic dirfile field
16
17

SYNOPSIS

19       #include <getdata.h>
20
21       double gd_framenum_subset(DIRFILE *dirfile, const char *field_code,
22              double value, off_t field_start, off_t field_end);
23
24       double gd_framenum(DIRFILE *dirfile, const char *field_code, double
25              value);
26
27

DESCRIPTION

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
35       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
41       The    gd_framenum()    function    is    equivalent     to     calling
42       gd_framenum_subset() with field_start and field_end equal to zero.
43
44       The  field  must be monotonic (either increasing or decreasing) between
45       the supplied limits.  It is not required to be strictly monotonic.
46
47       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
54       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
63       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
69       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
73

RETURN VALUE

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
81       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
86       GD_E_ALLOC
87               The library was unable to allocate memory.
88
89       GD_E_BAD_CODE
90               The field specified by field_code was not found.
91
92       GD_E_BAD_DIRFILE
93               The supplied dirfile was invalid.
94
95       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
99       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
104       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
109       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
114       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
117       GD_E_LUT
118               A LINTERP table was malformed.
119
120       GD_E_RANGE
121               The specified field is constant between the supplied limits.
122
123       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
128       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
133       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
138       A  descriptive  error  string  for the error may be obtained by calling
139       gd_error_string(3).
140
141

HISTORY

143       The get_framenum() and get_framenum_subset() functions appeared in Get‐
144       Data-0.6.0.
145
146       In  GetData-0.7.0,  these  functions  were renamed to gd_framenum() and
147       gd_framenum_subset().
148
149

SEE ALSO

151       gd_error(3),  gd_error_string(3),   gd_frameoffset(3),   gd_nframes(3),
152       gd_open(3)
153
154
155
156Version 0.10.0                 25 December 2016          gd_framenum_subset(3)
Impressum