gd_framenum_subset(3)

💖 gd_framenum_subset — bestie, let's reverse-engineer a field 💖

okay so this is the gd_framenum_subset(3) page from the GETDATA manual, and honestly? it's giving "detective but for numbers". we're doing a reverse look-up on a monotonic dirfile field. iykyk. 🕵️♀️✨

✨ NAME ✨

gd_framenum_subset, gd_framenum — perform a reverse look-up on a monotonic dirfile field. periodt. 💅

🦋 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 🌸

so gd_framenum_subset() queries a dirfile(5) database that you hand it as dirfile, and it gives you back the fractional frame number where the field named by field_code equals value. and field_code? it can totally contain a representation suffix, no big deal. 👑

but here's the twist — it only looks at the field between the frame limits field_start and field_end. boundaries, bestie. we respect them.

• if field_start is zero, the frame offset of the field gets used as the lower limit instead. and lowkey? that offset could be zero too — check gd_frameoffset(3) if you don't believe me. 🫶
• if field_end is zero, the number of frames in the dirfile gets used as the upper limit instead — that's whatever gd_nframes(3) reports.

and gd_framenum()? it's literally just gd_framenum_subset() with field_start and field_end both set to zero. same energy, fewer arguments. 💫

the field must be monotonic (either increasing or decreasing) between the limits you supply. it does not have to be strictly monotonic though. we're chill like that.

interpolation tea ☕: if the value you're searching for lands between two sample values, the frame number you get back is calculated by linear interpolation of the field between those two samples. and if more than one consecutive sample equals the value you're searching for? you get the fractional frame number of one of those samples, and no, it won't tell you which one. mystery behaviour, honestly iconic. 🙈

extrapolation tea 🫖: if the value you're searching for is found to lie outside the supplied limits, the first two or last two samples of the field get used to linearly extrapolate the returned frame number. and if those two samples happen to have the same value? you get positive or negative infinity. 😭

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. no cap, that's just how it is.

all computation is done in double precision. so if you use this on a 64-bit integer field with more precision than a double precision floating point number can hold, your returned value may be inaccurate. 💀

trying to use this function on a complex valued field = error. and if the field is constant across the entire range, that's an error too — even if the value you're searching for is equal to the constant value of the field. the disrespect of it all.

👑 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. and bestie, this might be any number — even values outside of the supplied limits, all the way up to and including positive or negative infinity. ✨

on error, these functions return an IEEE-754 conforming not-a-number (NaN), and store a negative-valued error code in the DIRFILE object, which you can retrieve with a subsequent call to gd_error(3). the possible error codes are:

• GD_E_ALLOC — the library was unable to allocate memory. 💀
• GD_E_BAD_CODE — the field specified by field_code was not found. girl, where.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. 🚩
• 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 — the field specified by field_code was not a vector field. Or, a scalar field was found where a vector field was expected in the definition of the field or one of its inputs.
• 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. fr fr, they wanna know.
• GD_E_IO — an error occurred while trying to open or read from a file on disk containing a raw field or LINTERP table.
• GD_E_LUT — a LINTERP table was malformed. not the malformed LINTERP table 😭
• GD_E_RANGE — the specified field is constant between the supplied limits.
• 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.

and a descriptive error string for the error may be obtained by calling gd_error_string(3). slay, now you know what went wrong. 💅

🌈 HISTORY 🌈

the get_framenum() and get_framenum_subset() functions appeared in GetData-0.6.0. glow-up era.

in GetData-0.7.0, these functions were renamed to gd_framenum() and gd_framenum_subset(). rebrand of the century, honestly. 💖

🎀 SEE ALSO 🎀

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

Version 0.10.0 · 25 December 2016 — that's the source, the version, and the date, bestie, and that's the whole page. go forth and reverse look-up. mwah. 💋🦋✨