.\" header.tmac.  GetData manual macros.
.\"
.\" Copyright (C) 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.

.\" Format a function name with optional trailer: func_name()trailer
.de FN \" func_name [trailer]
.nh
.BR \\$1 ()\\$2
.hy
..

.\" Format a reference to section 3 of the manual: name(3)trailer
.de F3 \" func_name [trailer]
.nh
.BR \\$1 (3)\\$2
.hy
..

.\" Format the header of a list of definitons
.de DD \" name alt...
.ie "\\$2"" \{ \
.TP 8
.PD
.B \\$1 \}
.el \{ \
.PP
.B \\$1
.PD 0
.DD \\$2 \\$3 \}
..

.\" Start a code block: Note: groff defines an undocumented .SC for
.\" Bell Labs man legacy reasons.
.de SC
.fam C
.na
.nh
..

.\" End a code block
.de EC
.hy
.ad
.fam
..

.\" Format a structure pointer member: struct->member\fRtrailer
.de SPM \" struct member trailer
.nh
.ie "\\$3"" .IB \\$1 ->\: \\$2
.el .IB \\$1 ->\: \\$2\fR\\$3
.hy
..

.\" Format a function argument
.de ARG \" name trailer
.nh
.ie "\\$2"" .I \\$1
.el .IR \\$1 \\$2
.hy
..

.\" Hyphenation exceptions
.hw sarray carray lincom linterp
.\" gd_framenum_subset.3.  The gd_framenum man page.
.\"
.\" Copyright (C) 2009, 2010, 2011, 2014, 2016 D.V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_framenum_subset 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_framenum_subset, gd_framenum \(em perform a reverse look-up on a
monotonic dirfile field

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "double gd_framenum_subset(DIRFILE *" dirfile ", const char *" field_code ,
.BI "double " value ", off_t " field_start ", off_t " field_end );
.HP
.BI "double gd_framenum(DIRFILE *" dirfile ", const char *" field_code ,
.BI "double " value );
.EC

.SH DESCRIPTION
The
.FN gd_framenum_subset
function queries a dirfile(5) database specified by
.ARG dirfile
and returns the fractional frame number at which the field specified by
.ARG field_code ,
which may contain a representation suffix, equals
.ARG value ,
by considering the field between the frame limits
.ARG field_start
and
.ARG field_end .

If
.ARG field_start
is zero, the frame offset of the field is used as the lower limit instead (which
may, in fact, be zero; see
.F3 gd_frameoffset ).
If
.ARG field_end
is zero, the number of frames in the dirfile, as reported by
.F3 gd_nframes ,
is used instead as the upper limit.

The
.FN gd_framenum
function is equivalent to calling
.FN gd_framenum_subset
with
.ARG field_start
and
.ARG 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, an error results, even if
the value to search for is equal to the constant value of the field.

.SH 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.  This might be any number, even values
outside of the supplied limits, 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
.B DIRFILE
object which may be retrieved by a subsequent call to
.F3 gd_error .
Possible error codes are:
.DD GD_E_ALLOC
The library was unable to allocate memory.
.DD GD_E_BAD_CODE
The field specified by
.ARG field_code
was not found.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_SCALAR
A scalar field used in the definition of the field was not found, or was not of
scalar type.
.DD GD_E_DIMENSION
The field specified by
.ARG 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.
.DD 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.
.DD 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.
.DD GD_E_IO
An error occurred while trying to open or read from a file on disk containing
a raw field or LINTERP table.
.DD GD_E_LUT
A LINTERP table was malformed.
.DD GD_E_RANGE
The specified field is constant between the supplied limits.
.DD GD_E_RECURSE_LEVEL
Too many levels of recursion were encountered while trying to resolve
.ARG field_code .
This usually indicates a circular dependency in field specification in the
dirfile.
.DD 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.
.DD 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.
.PP
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .

.SH HISTORY
The
.FN get_framenum
and
.FN get_framenum_subset
functions appeared in GetData-0.6.0.

In GetData-0.7.0, these functions were renamed to
.FN gd_framenum
and
.FN gd_framenum_subset .

.SH SEE ALSO
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_frameoffset ,
.F3 gd_nframes ,
.F3 gd_open