.TH READ_FUNC 3carl CARL
.SH NAME
read_func_file, read_func_fid
\- routines to read floatsam sample streams into standard CARL FUNCTION format
structures
.SH SYNOPSIS
.nf
.B #include <carl/carl.h>
.B #include <carl/defaults.h>
.sp
.B FUNCTION * read_func_file(name, def_seq_type)
.B	char *name;
.B	char *def_seq_type;
.sp
.B FUNCTION * read_func_fid(fd, def_seq_type)
.B	FILE *fd;
.B	char *def_seq_type;
.fi
.SH DESCRIPTION
.TP
read_func_fid()
uses a FILE pointer to a file opened with fopen(3) to read a stream
of 
.I floatsams
with
.I fgetfloat(3carl)
and build an internal FUNCTION structure, described below.
.TP 
read_func_file()
is a front end for
.B read_func_fid() 
which takes a file name to be opened. 
.SH EXEGESIS
These routines provide a uniform way of reading data which represent
control functions (or arbitrary data) in floatsam format from a UNIX
file into a program.  
.B read_func_fid()
reads any header on the data with
.I getheader(3carl)
and uses the properties to determine the format of the FUNCTION structure.
If the header contains a H_SEQUENCE property name with the
property value of H_MONO_IN_X, the data is presumed
to be an ordinary stream of floatsam values without abcissas.  
If the H_SEQUENCE property name has a value of H_XY_PAIRS, the
data is presumed to be interleaved [x,y] floatsam pairs, representing
piecewise linear functions.
If the data has no header, the
.B def_seq_type 
argument to the functions determines the default sequence type for
the data.  It should have a value of either H_MONO_IN_X, or H_XY_PAIRS.
If a header is guaranteed, it can be NULL.
.SH FUNCTION STRUCTURE
The FUNCTION declaration looks like this: 
.RS .5i 
.nf
struct func {
	char *ftype;	/* function type: MONO_IN_X, or XY_PAIRS */
	char *fname;	/* function name */
	long flen;	/* function length */
	float *fxval;	/* x function values */
	float *fyval;	/* y function values */
}; 
typedef struct func FUNCTION;
.fi
.RE
.PP
The valid sequence types for the 
.B ftype 
subfield are H_MONO_IN_X for data monotonic in x,
and H_XY_PAIRS for data in [x,y] pairs.
For H_MONO_IN_X, the 
.B fxval
pointer is set to NULL.
.SH FILE
/carl/lib/libcarl.a
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
genxy(1carl),
floatsam(5carl),
getfloat(3carl).
.SH CODE EXAMPLE
A demo program which simply reads in functions and prints their
contents is in /mnt/carl/src/demo/read_function.c at CARL.
