Create a new table extension by writing the required keywords that
define the table structure. The required null primary array
will be created first if the file is initially completely empty. tbltype defines the type of table and can have values of ASCII_TBL or BINARY_TBL. Binary tables are generally preferred
because they are more efficient and support a greater range of column
datatypes than ASCII tables.

The nrows parameter gives the initial number of empty rows to be
allocated for the table; this should normally be set to 0. The tfields
parameter gives the number of columns in the table (maximum = 999).
The ttype, tform, and tunit parameters give the name, datatype, and
physical units of each column, and extname gives the name for the
table (the value of the EXTNAME keyword).
The FITS Standard recommends that only
letters, digits, and the underscore character be used in column names
with no embedded spaces. It is recommended that all the column names
in a given table be unique within the first 8 characters.

The following table
shows the TFORM column format values that are allowed in ASCII tables
and in binary tables:

Get the column number (starting with 1, not 0) of the column whose
name matches the specified template name. The only difference in
these 2 routines is that the 2nd one also returns the name of the
column that matched the template string.

Normally, casesen should
be set to CASEINSEN, but it may be set to CASESEN to force
the name matching to be case-sensitive.

The input template string gives the name of the desired column and
may include wildcard characters: a `*' matches any sequence of
characters (including zero characters), `?' matches any single
character, and `#' matches any consecutive string of decimal digits
(0-9). If more than one column name in the table matches the template
string, then the first match is returned and the status value will be
set to COL_NOT_UNIQUE as a warning that a unique match was not
found. To find the next column that matches the template, call this
routine again leaving the input status value equal to COL_NOT_UNIQUE. Repeat this process until status =
COL_NOT_FOUND is returned.

Return the datatype, vector repeat count, and the width in bytes of a
single column element for column number colnum. Allowed values
for the returned datatype in ASCII tables are: TSTRING, TSHORT,
TLONG, TFLOAT, and TDOUBLE. Binary tables support these additional
types: TLOGICAL, TBIT, TBYTE, TINT32BIT, TCOMPLEX and TDBLCOMPLEX. The
negative of the datatype code value is returned if it is a variable
length array column.

These 2 routines are similar, except that in the case of scaled
integer columns the 2nd routine, fit_get_eqcoltype, returns the
'equivalent' datatype that is needed to store the scaled values, which
is not necessarily the same as the physical datatype of the unscaled values
as stored in the FITS table. For example if a '1I' column in a binary
table has TSCALn = 1 and TZEROn = 32768, then this column effectively
contains unsigned short integer values, and thus the returned value of
typecode will be TUSHORT, not TSHORT. Or, if TSCALn or TZEROn are not
integers, then the equivalent datatype will be returned as TFLOAT or
TDOUBLE, depending on the size of the integer.

The repeat count is always 1 in ASCII tables.
The 'repeat' parameter returns the vector repeat count on the binary
table TFORMn keyword value. (ASCII table columns always have repeat
= 1). The 'width' parameter returns the width in bytes of a single
column element (e.g., a '10D' binary table column will have width =
8, an ASCII table 'F12.2' column will have width = 12, and a binary
table'60A' character string column will have width = 60); Note that
this routine supports the local convention for specifying arrays of
fixed length strings within a binary table character column using
the syntax TFORM = 'rAw' where 'r' is the total number of
characters (= the width of the column) and 'w' is the width of a
unit string within the column. Thus if the column has TFORM =
'60A12' then this means that each row of the table contains
5 12-character substrings within the 60-character field, and thus
in this case this routine will return typecode = TSTRING, repeat =
60, and width = 12. The number of substings in any binary table
character string field can be calculated by (repeat/width).
A null pointer may be given for any of the output parameters that
are not needed.

Insert or delete rows in a table. The blank rows are inserted
immediately following row frow. Set frow = 0 to insert rows
at the beginning of the table. The first 'delete' routine deletes nrows rows beginning with row firstrow. The 2nd delete routine
takes an input string listing the rows or row ranges to be deleted
(e.g., '2,4-7, 9-12'). The last delete routine takes an input long
integer array that specifies each individual row to be deleted. The
row lists must be sorted in ascending order. All these routines update
the value of the NAXIS2 keyword to reflect the new number of rows
in the table.

Insert or delete columns in a table. colnum gives the position
of the column to be inserted or deleted (where the first column of the
table is at position 1). ttype and tform give the column
name and column format, where the allowed format codes are listed above
in the description of the fits_create_table routine. The 2nd
'insert' routine inserts multiple columns, where ncols is the
number of columns to insert, and ttype and tform are
arrays of string pointers in this case.

Copy a column from one table HDU to another. If create_col = TRUE (i.e., not equal to zero),
then a new column will be inserted in the output table at position
outcolumn, otherwise the values in the existing output column will be
overwritten.

Write or read elements in column number colnum, starting with row
firstsrow and element firstelem (if it is a vector
column). firstelem is ignored if it is a scalar column. The nelements number of elements are read or written continuing on
successive rows of the table if necessary. array is the address
of an array which either contains the values to be written, or will
hold the returned values that are read. When reading, array must
have been allocated large enough to hold all the returned values.

There are 3 different 'write' column routines: The first simply writes
the input array into the column. The second is similar, except that it
substitutes the appropriate null pixel value in the column for any
input array values which are equal to *nulval (note that this
parameter gives the address of the null pixel value, not the value
itself). The third write routine sets the specified table elements
to a null value. New rows will be automatical added to the table
if the write operation extends beyond the current size of the table.

When reading a column, CFITSIO will substitute the value given by nulval for any undefined elements in the FITS column, unless nulval or *nulval = NULL, in which case no checks will be made
for undefined values when reading the column.

datatype specifies the datatype of the C array in the program,
which need not be the same as the intrinsic datatype of the column in
the FITS table. The following symbolic constants are allowed for the
value of datatype:

Note that TSTRING corresponds to the C char** datatype, i.e., a pointer to an array of pointers to an array
of characters.

Any column, regardless of it's intrinsic datatype, may be read as a
TSTRING character string. The display format of the returned
strings will be determined by the TDISPn keyword, if it exists,
otherwise a default format will be used depending on the datatype of
the column. The tablist example utility program (available from
the CFITSIO web site) uses this feature to display all the values in a
FITS table.

These are 2 of the most powerful routines in the CFITSIO library. (See
the full CFITSIO Reference Guide for a description of several related
routines). These routines can perform complicated transformations on
tables based on an input arithmetic expression which is evaluated for
each row of the table. The first routine will select or copy rows of
the table for which the expression evaluates to TRUE (i.e., not equal
to zero). The second routine writes the value of the expression to a
column in the output table. Rather than supplying the expression
directly to these routines, the expression may also be written to a
text file (continued over multiple lines if necessary) and the name of
the file, prepended with a '@' character, may be supplied as the value
of the 'expr' parameter (e.g. '@filename.txt').

The arithmetic expression may be a function of any column or keyword in
the input table as shown in these examples:

Most standard mathematical operators and functions are supported. If
the expression includes the name of a column, than the value in the
current row of the table will be used when evaluating the expression on
each row. An offset to an adjacent row can be specified by including
the offset value in curly brackets after the column name as shown in
one of the examples. Keyword values can be included in the expression
by preceding the keyword name with a `#' sign. See Section 5 of this
document for more discussion of the expression syntax.

gtifilter is a special function which tests whether the TIME column value in the input table falls within one or more Good
Time Intervals. By default, this function looks for a 'GTI' extension
in the same file as the input table. The 'GTI' table contains START
and STOP columns which define the range of
each good time interval. See section 5.4.3 for more details.

regfilter is another special function which selects rows based on
whether the spatial position associated with each row is located within
in a specified region of the sky. By default, the X and Y
columns in the input table are assumed to give the position of each row.
The spatial region is defined in an ASCII text file whose name is given
as the argument to the regfilter function. See section 5.4.4 for
more details.

The infptr and outfptr parameters in these routines may
point to the same table or to different tables. In fits_select_rows, if the input and output tables are the same then
the rows that do not satisfy the selection expression will be deleted
from the table. Otherwise, if the output table is different from the
input table then the selected rows will be copied from the input table
to the output table.

The output column in fits_calculator may or may not already
exist. If it exists then the calculated values will be written to that
column, overwriting the existing values. If the column doesn't exist
then the new column will be appended to the output table. The tform
parameter can be used to specify the datatype of the new column (e.g.,
the TFORM keyword value as in '1E', or '1J'). If tform = NULL then a default datatype will be used, depending on the
expression.

These 2 routines provide low-level access to tables and are mainly
useful as an efficient way to copy rows of a table from one file to
another. These routines simply read or write the specified number of
consecutive characters (bytes) in a table, without regard for column
boundaries. For example, to read or write the first row of a table,
set firstrow = 1, firstchar = 1, and nchars = NAXIS1 where
the length of a row is given by the value of the NAXIS1 header
keyword. When reading a table, array must have been declared at
least nchars bytes long to hold the returned string of bytes.