Main Page   Modules   Alphabetical List   Compound List   Compound Members  

Tables


Functions

cpl_table * cpl_table_new (int)
 Create an empty table structure. More...

cpl_table * cpl_table_new_from_model (cpl_table *table, int length)
 Create a table from a model table. More...

cpl_error_code cpl_table_new_column_int (cpl_table *table, const char *name)
 Create an empty integer column in a table. More...

cpl_error_code cpl_table_new_column_float (cpl_table *table, const char *name)
 Create an empty float column in a table. More...

cpl_error_code cpl_table_new_column_double (cpl_table *table, const char *name)
 Create an empty double column in a table. More...

cpl_error_code cpl_table_new_column_string (cpl_table *table, const char *name)
 Create an empty string column in a table. More...

cpl_error_code cpl_table_new_column_from_data_int (cpl_table *table, int *data, const char *name)
 Create in table a new integer column obtained from existing data. More...

cpl_error_code cpl_table_new_column_from_data_float (cpl_table *table, float *data, const char *name)
 Create in table a new float column obtained from existing data. More...

cpl_error_code cpl_table_new_column_from_data_double (cpl_table *table, double *data, const char *name)
 Create in table a new double column obtained from existing data. More...

cpl_error_code cpl_table_new_column_from_data_string (cpl_table *table, char **data, const char *name)
 Create in table a new string column obtained from existing data. More...

cpl_error_code cpl_table_copy_data (cpl_table *table, const char *name, double *data)
 Copy a numerical array to an existing table column. More...

cpl_error_code cpl_table_copy_data_int (cpl_table *table, const char *name, int *data)
 Copy existing data to a table integer column. More...

cpl_error_code cpl_table_copy_data_float (cpl_table *table, const char *name, float *data)
 Copy existing data to a table float column. More...

cpl_error_code cpl_table_copy_data_double (cpl_table *table, const char *name, double *data)
 Copy existing data to a table double column. More...

cpl_error_code cpl_table_copy_data_string (cpl_table *table, const char *name, char **data)
 Copy existing data to a table string column. More...

void cpl_table_delete (cpl_table *table)
 Delete a table. More...

int cpl_table_get_nrow (cpl_table *table)
 Get the number of rows in a table. More...

int cpl_table_get_ncol (cpl_table *table)
 Get the number of columns in a table. More...

cpl_type cpl_table_get_column_type (cpl_table *table, const char *name)
 Get the type of a table column. More...

cpl_error_code cpl_table_set_column_unit (cpl_table *table, const char *name, const char *unit)
 Give a new unit to a table column. More...

const char * cpl_table_get_column_unit (cpl_table *table, const char *name)
 Get the unit of a table column. More...

cpl_error_code cpl_table_set_column_format (cpl_table *table, const char *name, const char *format)
 Give a new format to a table column. More...

const char * cpl_table_get_column_format (cpl_table *table, const char *name)
 Get the format of a table column. More...

int * cpl_table_get_data_int (cpl_table *table, const char *name)
 Get a pointer to integer column data. More...

float * cpl_table_get_data_float (cpl_table *table, const char *name)
 Get a pointer to float column data. More...

double * cpl_table_get_data_double (cpl_table *table, const char *name)
 Get a pointer to double column data. More...

char ** cpl_table_get_data_string (cpl_table *table, const char *name)
 Get a pointer to string column data. More...

cpl_error_code cpl_table_delete_column (cpl_table *table, const char *name)
 Delete a column from a table. More...

cpl_error_code cpl_table_erase_segment (cpl_table *table, int start, int count)
 Delete a table segment. More...

cpl_error_code cpl_table_erase_unselected (cpl_table *table)
 Keep just the selected rows of a table. More...

cpl_error_code cpl_table_insert_segment (cpl_table *table, int start, int count)
 Insert a segment of null rows into table data. More...

int cpl_table_compare_structures (cpl_table *table1, cpl_table *table2)
 Compare the structure of two tables. More...

cpl_error_code cpl_table_merge (cpl_table *target_table, cpl_table *insert_table, int row)
 Merge two tables that have the same structure. More...

double cpl_table_get (cpl_table *table, const char *name, int row, int *null)
 Read a value from a numerical column. More...

int cpl_table_get_int (cpl_table *table, const char *name, int row, int *null)
 Read a value from an integer column. More...

float cpl_table_get_float (cpl_table *table, const char *name, int row, int *null)
 Read a value from a float column. More...

double cpl_table_get_double (cpl_table *table, const char *name, int row, int *null)
 Read a value from a double column. More...

const char * cpl_table_get_string (cpl_table *table, const char *name, int row)
 Read a value from a string column. More...

cpl_error_code cpl_table_set (cpl_table *table, const char *name, int row, double value)
 Write a value to a numerical table column element. More...

cpl_error_code cpl_table_set_int (cpl_table *table, const char *name, int row, int value)
 Write a value to an integer table column element. More...

cpl_error_code cpl_table_set_float (cpl_table *table, const char *name, int row, float value)
 Write a value to a float table column element. More...

cpl_error_code cpl_table_set_double (cpl_table *table, const char *name, int row, double value)
 Write a value to a double table column element. More...

cpl_error_code cpl_table_set_string (cpl_table *table, const char *name, int row, const char *value)
 Write a character string to a string table column element. More...

cpl_error_code cpl_table_set_null (cpl_table *table, const char *name, int row)
 Flag a column element as invalid. More...

cpl_error_code cpl_table_fill_column (cpl_table *table, const char *name, int start, int count, double value)
 Write a value to a numerical column segment. More...

cpl_error_code cpl_table_fill_column_int (cpl_table *table, const char *name, int start, int count, int value)
 Write a value to an integer column segment. More...

cpl_error_code cpl_table_fill_column_float (cpl_table *table, const char *name, int start, int count, float value)
 Write a value to a float column segment. More...

cpl_error_code cpl_table_fill_column_double (cpl_table *table, const char *name, int start, int count, double value)
 Write a value to a double column segment. More...

cpl_error_code cpl_table_fill_column_string (cpl_table *table, const char *name, int start, int count, char *value)
 Write a character string to a string column segment. More...

cpl_error_code cpl_table_fill_column_null (cpl_table *table, const char *name, int start, int count)
 Invalidate a column segment. More...

int cpl_table_value_is_null (cpl_table *table, const char *name, int row)
 Check if a column element is invalid. More...

int cpl_table_column_any_null (cpl_table *table, const char *name)
 Check if a column contains at least one invalid value. More...

int cpl_table_column_any_valid (cpl_table *table, const char *name)
 Check if a column contains at least one valid value. More...

int cpl_table_column_count_nulls (cpl_table *table, const char *name)
 Count number of invalid values in a table column. More...

cpl_error_code cpl_table_move_column (cpl_table *to_table, const char *name, cpl_table *from_table)
 Move a column from a table to another. More...

cpl_error_code cpl_table_duplicate_column (cpl_table *to_table, const char *to_name, cpl_table *from_table, const char *from_name)
 Copy a column from a table to another. More...

cpl_error_code cpl_table_rename_column (cpl_table *table, const char *from_name, const char *to_name)
 Rename a table column. More...

int cpl_table_column_exists (cpl_table *table, const char *name)
 Check if a column with a given name exists. More...

int cpl_table_is_empty (cpl_table *table)
 Check if a table has columns. More...

const char * cpl_table_get_column_name (cpl_table *table)
 Get table columns names. More...

cpl_error_code cpl_table_resize (cpl_table *table, int new_length)
 Resize a table to a new number of rows. More...

cpl_table * cpl_table_duplicate (cpl_table *table)
 Make a copy of a table. More...

cpl_table * cpl_table_extract (cpl_table *table, int start, int count)
 Create a table from a section of another table. More...

cpl_error_code cpl_table_convert_column (cpl_table *table, const char *from_name, const char *to_name, cpl_type type)
 Cast a numeric column to a new numeric type column. More...

cpl_error_code cpl_table_add_columns (cpl_table *table, const char *to_name, const char *from_name)
 Add the values of two numeric table columns. More...

cpl_error_code cpl_table_subtract_columns (cpl_table *table, const char *to_name, const char *from_name)
 Subtract two numeric table columns. More...

cpl_error_code cpl_table_multiply_columns (cpl_table *table, const char *to_name, const char *from_name)
 Multiply two numeric table columns. More...

cpl_error_code cpl_table_divide_columns (cpl_table *table, const char *to_name, const char *from_name)
 Divide two numeric table columns. More...

cpl_error_code cpl_table_const_op (cpl_table *table, const char *name, double value, int operation)
 Arithmetic between a numerical column and a constant. More...

cpl_error_code cpl_table_column_add_constant (cpl_table *table, const char *name, double value)
 Add a constant value to a numerical column. More...

cpl_error_code cpl_table_column_subtract_constant (cpl_table *table, const char *name, double value)
 Subtract a constant value from a numerical column. More...

cpl_error_code cpl_table_column_multiply_constant (cpl_table *table, const char *name, double value)
 Multiply a numerical column by a constant. More...

cpl_error_code cpl_table_column_divide_constant (cpl_table *table, const char *name, double value)
 Divide a numerical column by a constant. More...

cpl_error_code cpl_table_column_logarithm (cpl_table *table, const char *name, double base)
 Compute the logarithm of column values. More...

cpl_error_code cpl_table_column_exponential (cpl_table *table, const char *name, double base)
 Compute the exponential of column values. More...

cpl_error_code cpl_table_column_power (cpl_table *table, const char *name, double exponent)
 Compute the power of column values. More...

double cpl_table_column_mean (cpl_table *table, const char *name)
 Compute the mean value of a numerical column. More...

double cpl_table_column_median (cpl_table *table, const char *name)
 Compute the median value of a numerical column. More...

double cpl_table_column_max (cpl_table *table, const char *name)
 Get maximum value in a numerical column. More...

double cpl_table_column_min (cpl_table *table, const char *name)
 Get minimum value in a numerical column. More...

cpl_error_code cpl_table_column_maxpos (cpl_table *table, const char *name, int *row)
 Get position of maximum in a numerical column. More...

cpl_error_code cpl_table_column_minpos (cpl_table *table, const char *name, int *row)
 Get position of minimum in a numerical column. More...

cpl_error_code cpl_table_prune (cpl_table *table)
 Remove from a table columns and rows just containing invalid elements. More...

cpl_error_code cpl_table_clean (cpl_table *table)
 Remove from a table all columns just containing invalid elements, and then all rows containing at least one invalid element. More...

cpl_error_code cpl_table_select_row (cpl_table *table, int row)
 Flag a table row as selected. More...

cpl_error_code cpl_table_select_all (cpl_table *table)
 Select all table rows. More...

cpl_error_code cpl_table_unselect_row (cpl_table *table, int row)
 Flag a table row as unselected. More...

cpl_error_code cpl_table_unselect_all (cpl_table *table)
 Unselect all table rows. More...

void cpl_table_show (cpl_table *table)
 Describe the structure and the contents of a table. More...

void cpl_table_print (cpl_table *table, int start, int count)
 Print a table. More...

cpl_error_code cpl_table_shift_column (cpl_table *table, const char *name, int shift)
 Shift the positions of numeric column values. More...

cpl_error_code cpl_table_column_code_null_int (cpl_table *table, const char *name, int code)
 Write to invalid integer column elements a numeric code. More...

cpl_error_code cpl_table_column_code_null_float (cpl_table *table, const char *name, float code)
 Write to invalid float column elements a numeric code. More...

cpl_error_code cpl_table_column_code_null_double (cpl_table *table, const char *name, double code)
 Write to invalid double column elements a numeric code. More...

int cpl_table_and_select_int (cpl_table *table, const char *name, cpl_table_select_operator operator, const int value)
 Select from selected table rows, by comparing integer column values with a constant. More...

int cpl_table_or_select_int (cpl_table *table, const char *name, cpl_table_select_operator operator, const int value)
 Select from unselected table rows, by comparing column values with a constant. More...

int cpl_table_and_select_float (cpl_table *table, const char *name, cpl_table_select_operator operator, const float value)
 Select from selected table rows, by comparing float column values with a constant. More...

int cpl_table_or_select_float (cpl_table *table, const char *name, cpl_table_select_operator operator, const float value)
 Select from unselected table rows, by comparing column values with a constant. More...

int cpl_table_and_select_double (cpl_table *table, const char *name, cpl_table_select_operator operator, const double value)
 Select from selected table rows, by comparing double column values with a constant. More...

int cpl_table_or_select_double (cpl_table *table, const char *name, cpl_table_select_operator operator, const double value)
 Select from unselected table rows, by comparing column values with a constant. More...

int cpl_table_and_select_string (cpl_table *table, const char *name, cpl_table_select_operator operator, const char *string)
 Select from selected table rows, by comparing column values with a character string. More...

int cpl_table_or_select_string (cpl_table *table, const char *name, cpl_table_select_operator operator, const char *string)
 Select from unselected table rows, by comparing column values with a constant. More...

int cpl_table_and_select_nulls (cpl_table *table, const char *name)
 Select from selected table rows all rows with invalid values in one column. More...

int cpl_table_or_select_nulls (cpl_table *table, const char *name)
 Select from unselected table rows all rows with invalid values in one column. More...

int cpl_table_and_select_segment (cpl_table *table, int start, int count)
 Select from selected rows only those within a table segment. More...

int cpl_table_or_select_segment (cpl_table *table, int start, int count)
 Select from unselected rows only those within a table segment. More...

int cpl_table_reverse_selection (cpl_table *table)
 Select unselected table rows, and unselect selected ones. More...

int cpl_table_and_select (cpl_table *table, const char *name1, cpl_table_select_operator operator, const char *name2)
 Select from selected table rows, by comparing the values of two columns. More...

int cpl_table_or_select (cpl_table *table, const char *name1, cpl_table_select_operator operator, const char *name2)
 Select from unselected table rows, by comparing the values of two columns. More...

cpl_table * cpl_table_extract_selected (cpl_table *table)
 Create a new table from the selected rows of another table. More...

cpl_error_code cpl_table_sort (cpl_table *table, char **names, int ncol, int *reverse)
 Sort table rows according to columns values. More...

cpl_table * cpl_table_load (char *filename, int xtnum, int check_nulls)
 Load a FITS table extension into a new cpl_table. More...

cpl_error_code cpl_table_save (cpl_table *table, cpl_plist *pheader, cpl_plist *header, char *filename, int append)
 Save a cpl_table to a FITS file. More...


Detailed Description

This module provides functions to create, use, and destroy a cpl_table. A cpl_table is made of columns, and a column consists of an array of elements of a given type. Currently three numerical types are supported, CPL_TYPE_INT, CPL_TYPE_FLOAT, and CPL_TYPE_DOUBLE, plus a type indicating columns made of character strings, CPL_TYPE_STRING. A table column should only be accessed through the cpl_table interface, by specifying its name. The ordering of the columns within a table is undefined: a cpl_table is not an n-tuple of columns, but just a set of columns. The N elements of a column are counted from 0 to N-1, with element 0 on top. The set of all the table columns elements with the same index constitutes a table row, and table rows are counted according to the same convention. It is possible to flag each cpl_table row as `selected' or `unselected', and each column element as `valid' or `invalid' (null flagged). Selecting table rows is mainly a way to extract just those table parts fulfilling any given condition, while invalidating column elements is a way to exclude such elements from any computation.

Note:
The cpl_table pointers specified in the argument list of all the cpl_table functions must point to valid objects: these functions do not perform any check in this sense. Only in the particular case of a NULL pointer the functions will stop with an assertion failure, unless differently specified. An assertion failure would also be generated in case a NULL pointer would be used in place of the name of a table column to access.
Synopsis:
   #include <cpl_table.h>

Function Documentation

cpl_error_code cpl_table_add_columns cpl_table *    table,
const char *    to_name,
const char *    from_name
 

Add the values of two numeric table columns.

Parameters:
table  Pointer to table.
to_name  Name of target column.
from_name  Name of source column.
Returns:
CPL_ERROR_NONE on success. If any specified column is not found in the input table, a CPL_ERROR_DATA_NOT_FOUND is returned. If any specified column is of type CPL_TYPE_STRING, a CPL_ERROR_INVALID_TYPE is returned.
The columns are summed element by element, and the result of the sum is stored in the target column. The columns' types may differ, and in that case the operation would be performed using the standard C implicit casting, with a final cast of the result to the target column type. Also null flags are upgraded: if either or both members of the sum are invalid, the result will be invalid too. Underflows and overflows are ignored, and the table selection flags are always reset.

int cpl_table_and_select cpl_table *    table,
const char *    name1,
cpl_table_select_operator    operator,
const char *    name2
 

Select from selected table rows, by comparing the values of two columns.

Parameters:
table  Pointer to table.
name1  Name of first table column.
operator  Relational operator.
name2  Name of second table column.
Returns:
Number of selected rows, or a negative number in case of error. If a column is not found in the input table, a CPL_ERROR_DATA_NOT_FOUND is returned. If a column is of type CPL_TYPE_STRING, a CPL_ERROR_INVALID_TYPE is returned.
Both columns must be numerical. For all the already selected table rows, the values of the specified columns are compared. The table rows not fulfilling the comparison are unselected. Invalid elements from either columns never fulfill any comparison by definition. Allowed relational operators are EQUAL_TO, NOT_EQUAL_TO, GREATER_THAN, NOT_GREATER_THAN, LESS_THAN, NOT_LESS_THAN. See also the function cpl_table_or_select().

int cpl_table_and_select_double cpl_table *    table,
const char *    name,
cpl_table_select_operator    operator,
const double    value
 

Select from selected table rows, by comparing double column values with a constant.

Parameters:
table  Pointer to table.
name  Column name.
operator  Relational operator.
value  Reference value.
Returns:
Number of selected rows, or a negative number in case of error. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is set.
See the description of the function cpl_table_and_select_int().

int cpl_table_and_select_float cpl_table *    table,
const char *    name,
cpl_table_select_operator    operator,
const float    value
 

Select from selected table rows, by comparing float column values with a constant.

Parameters:
table  Pointer to table.
name  Column name.
operator  Relational operator.
value  Reference value.
Returns:
Number of selected rows, or a negative number in case of error. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is set.
See the description of the function cpl_table_and_select_int().

int cpl_table_and_select_int cpl_table *    table,
const char *    name,
cpl_table_select_operator    operator,
const int    value
 

Select from selected table rows, by comparing integer column values with a constant.

Parameters:
table  Pointer to table.
name  Column name.
operator  Relational operator.
value  Reference value.
Returns:
Number of selected rows, or a negative number in case of error. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is set.
For all the already selected table rows, the values of the specified column are compared with the reference value. All table rows not fulfilling the comparison are unselected. An invalid element never fulfills any comparison by definition. Allowed relational operators are EQUAL_TO, NOT_EQUAL_TO, GREATER_THAN, NOT_GREATER_THAN, LESS_THAN, and NOT_LESS_THAN. See also the function cpl_table_or_select_int().

int cpl_table_and_select_nulls cpl_table *    table,
const char *    name
 

Select from selected table rows all rows with invalid values in one column.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Number of selected rows, or a negative number in case of error. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is set.
For all the already selected table rows, all the rows containing valid values at the specified column are unselected. See also the function cpl_table_or_select_nulls().

int cpl_table_and_select_segment cpl_table *    table,
int    start,
int    count
 

Select from selected rows only those within a table segment.

Parameters:
table  Pointer to table.
start  First row of table segment.
count  Length of segment.
Returns:
Number of selected rows, or a negative number in case of error.
All the selected table rows that are outside the specified interval are unselected. See also the function cpl_table_or_select_segment().

int cpl_table_and_select_string cpl_table *    table,
const char *    name,
cpl_table_select_operator    operator,
const char *    string
 

Select from selected table rows, by comparing column values with a character string.

Parameters:
table  Pointer to table.
name  Column name.
operator  Relational operator.
string  Reference character string.
Returns:
Number of selected rows, or a negative number in case of error. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_STRING, a CPL_ERROR_TYPE_MISMATCH is set. If an invalid regular expression is passed, a CPL_ERROR_ILLEGAL_INPUT is set.
For all the already selected table rows, the strings of the specified column are compared with the reference string. The comparison function used is the C standard strcmp(), but in case the relational operators EQUAL_TO or NOT_EQUAL_TO are specified, the comparison string is treated as a regular expression. All table rows not fulfilling the comparison are unselected. An invalid element never fulfills any comparison by definition. Allowed relational operators are EQUAL_TO, NOT_EQUAL_TO, GREATER_THAN, NOT_GREATER_THAN, LESS_THAN, and NOT_LESS_THAN. See also the function cpl_table_or_select_string().

cpl_error_code cpl_table_clean cpl_table *    table
 

Remove from a table all columns just containing invalid elements, and then all rows containing at least one invalid element.

Parameters:
table  Pointer to table.
Returns:
CPL_ERROR_NONE on success. If the input table contains just invalid elements, a CPL_ERROR_ILLEGAL_OUTPUT is returned.
Firstly, all columns consisting just of invalid elements are deleted from the table. Next, the remaining table rows containing at least one invalid element are also deleted from the table. The selection flags are reset. The pointers to data may change, therefore pointers previously retrieved by calling cpl_table_get_data_int(), cpl_table_get_data_string(), etc., should be discarded.

cpl_error_code cpl_table_column_add_constant cpl_table *    table,
const char *    name,
double    value
 

Add a constant value to a numerical column.

Parameters:
table  Pointer to table.
name  Column name.
value  Value to add.
Returns:
CPL_ERROR_NONE on success. If the specified column is not found in the input table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is of type CPL_TYPE_STRING, a CPL_ERROR_INVALID_TYPE is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. Existing null flags marking invalid column elements are not modified by this operation, but the table selection flags are always reset.

int cpl_table_column_any_null cpl_table *    table,
const char *    name
 

Check if a column contains at least one invalid value.

Parameters:
table  Pointer to table.
name  Name of table column to access.
Returns:
1 if the column contains at least one null, 0 if not. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set.
Check if there are null values in a column.

int cpl_table_column_any_valid cpl_table *    table,
const char *    name
 

Check if a column contains at least one valid value.

Parameters:
table  Pointer to table.
name  Name of table column to access.
Returns:
1 if the column contains at least one valid value, 0 if not. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set.
Check if there are valid values in a column.

cpl_error_code cpl_table_column_code_null_double cpl_table *    table,
const char *    name,
double    code
 

Write to invalid double column elements a numeric code.

Parameters:
table  Pointer to table containing the column.
name  Column name.
code  Code to write to invalid column elements.
Returns:
CPL_ERROR_NONE on success. If the specified column is not found, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is returned.
Table column elements containing invalid values are always flagged internally as nulls. In the column internal data buffer, that may be directly accessed calling the function cpl_table_get_data_double(), invalid elements generally contain garbage. It is for this reason that before directly accessing the column data buffer it would be appropriate to replace the garbage with a conventional value (or code). This value would supposedly be recognised and handled properly by a given foreign method applied to the pointed data buffer. Note that assigning a code to invalid column values will not make them valid. Note also that the code is just momentarily assigned to the existing invalid values, and would not be maintained in any way during further processing of the table. For this reason the code should be applied just before it is actually needed.

cpl_error_code cpl_table_column_code_null_float cpl_table *    table,
const char *    name,
float    code
 

Write to invalid float column elements a numeric code.

Parameters:
table  Pointer to table containing the column.
name  Column name.
code  Code to write to invalid column elements.
Returns:
CPL_ERROR_NONE on success. If the specified column is not found, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is returned.
Table column elements containing invalid values are always flagged internally as nulls. In the column internal data buffer, that may be directly accessed calling the function cpl_table_get_data_float(), invalid elements generally contain garbage. It is for this reason that before directly accessing the column data buffer it would be appropriate to replace the garbage with a conventional value (or code). This value will supposedly be recognised and handled properly by a given foreign method applied to the pointed data buffer. Note that assigning a code to invalid column values will not make them valid. Note also that the code is just momentarily assigned to the existing invalid values, and would not be maintained in any way during further processing of the table. For this reason the code should be applied just before it is actually needed.

cpl_error_code cpl_table_column_code_null_int cpl_table *    table,
const char *    name,
int    code
 

Write to invalid integer column elements a numeric code.

Parameters:
table  Pointer to table containing the column.
name  Column name.
code  Code to write to invalid column elements.
Returns:
CPL_ERROR_NONE on success. If the specified column is not found, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is returned.
Table column elements containing invalid values are always flagged internally as nulls. In the column internal data buffer, that may be directly accessed calling the function cpl_table_get_data_int(), invalid elements generally contain garbage. It is for this reason that before directly accessing the column data buffer it would be appropriate to replace the garbage with a conventional value (or code). This value will supposedly be recognised and handled properly by a given foreign method applied to the pointed data buffer. Note that assigning a code to invalid column values will not make them valid. Note also that the code is just momentarily assigned to the existing invalid values, and would not be maintained in any way during further processing of the table. For this reason the code should be applied just before it is actually needed.

int cpl_table_column_count_nulls cpl_table *    table,
const char *    name
 

Count number of invalid values in a table column.

Parameters:
table  Pointer to table.
name  Name of table column to examine.
Returns:
Number of nulls in a table column. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set.
Count number of nulls in a table column. If the column doesn't exist, zero is returned.

cpl_error_code cpl_table_column_divide_constant cpl_table *    table,
const char *    name,
double    value
 

Divide a numerical column by a constant.

Parameters:
table  Pointer to table.
name  Column name.
value  Divisor value.
Returns:
CPL_ERROR_NONE on success. If the specified column is not found in the input table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is of type CPL_TYPE_STRING, a CPL_ERROR_INVALID_TYPE is returned. If the input value is 0.0, a CPL_ERROR_DIVISION_BY_ZERO is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. Existing null flags marking invalid column elements are not modified by this operation, but the table selection flags are always reset. Only in the case of division by zero the table is left intact, and an error is returned.

int cpl_table_column_exists cpl_table *    table,
const char *    name
 

Check if a column with a given name exists.

Parameters:
table  Pointer to table.
name  Name of table column.
Returns:
0 if column doesn't exist.
Check if a column with a given name exists in the specified table.

cpl_error_code cpl_table_column_exponential cpl_table *    table,
const char *    name,
double    base
 

Compute the exponential of column values.

Parameters:
table  Pointer to table.
name  Column name.
base  Exponential base.
Returns:
See function cpl_table_column_add_constant().
Each column element is replaced by its exponential in the specified base. The base must be positive, or an assertion failure will be generated. The operation is always performed in double precision, with a final cast of the result to the target column type. Existing null flags are not modified by this operation, but the table selection flags are always reset.

cpl_error_code cpl_table_column_logarithm cpl_table *    table,
const char *    name,
double    base
 

Compute the logarithm of column values.

Parameters:
table  Pointer to table.
name  Table column name.
base  Logarithm base.
Returns:
See function cpl_table_column_add_constant().
Each column element is replaced by its logarithm in the specified base. The base must be positive, or an assertion failure will be generated. The operation is always performed in double precision, with a final cast of the result to the target column type. Existing null flags are not modified by this operation, but new null flags are added to invalidate non-positive column values. The table selection flags are always reset.

double cpl_table_column_max cpl_table *    table,
const char *    name
 

Get maximum value in a numerical column.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Maximum value. See documentation of cpl_table_column_mean().
See the description of the function cpl_table_column_mean().

cpl_error_code cpl_table_column_maxpos cpl_table *    table,
const char *    name,
int *    row
 

Get position of maximum in a numerical column.

Parameters:
table  Pointer to table.
name  Column name.
row  Returned position of maximum value.
Returns:
CPL_ERROR_NONE on success. If either the specified column is not found in the input table, or it contains just invalid elements, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is of type CPL_TYPE_STRING, a CPL_ERROR_INVALID_TYPE is returned.
Invalid column values are excluded from the search. The specified column must exist and must contain at least one valid value. The argument row will be assigned the position of the maximum value, where rows are counted starting from 0. If more than one column element correspond to the max value, the position with the lowest row number is returned. In case of error, row is left untouched. The table selection flags have no influence on the result.

double cpl_table_column_mean cpl_table *    table,
const char *    name
 

Compute the mean value of a numerical column.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Mean value. In case of error 0.0 is returned. If either the specified column is not found in the input table, or it contains just invalid elements, a CPL_ERROR_DATA_NOT_FOUND is set. If the column is of type CPL_TYPE_STRING, a CPL_ERROR_INVALID_TYPE is set.
Invalid column values are excluded from the computation. The specified column must exist and must contain at least one valid value. The table selection flags have no influence on the result.

double cpl_table_column_median cpl_table *    table,
const char *    name
 

Compute the median value of a numerical column.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Median value. See documentation of cpl_table_column_mean().
See the description of the function cpl_table_column_mean().

double cpl_table_column_min cpl_table *    table,
const char *    name
 

Get minimum value in a numerical column.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Minimum value. See documentation of cpl_table_column_mean().
See the description of the function cpl_table_column_mean().

cpl_error_code cpl_table_column_minpos cpl_table *    table,
const char *    name,
int *    row
 

Get position of minimum in a numerical column.

Parameters:
table  Pointer to table.
name  Column name.
row  Returned position of minimum value.
Returns:
See function cpl_table_column_maxpos().
See the description of the function cpl_table_column_maxpos().

cpl_error_code cpl_table_column_multiply_constant cpl_table *    table,
const char *    name,
double    value
 

Multiply a numerical column by a constant.

Parameters:
table  Pointer to table.
name  Column name.
value  Multiplication factor.
Returns:
See function cpl_table_column_add_constant().
See the description of the function cpl_table_column_add_constant().

cpl_error_code cpl_table_column_power cpl_table *    table,
const char *    name,
double    exponent
 

Compute the power of column values.

Parameters:
table  Pointer to table.
name  Column name.
exponent  Constant exponent.
Returns:
See function cpl_table_column_add_constant().
Each column element is replaced by its power to the specified exponent. The operation is always performed in double precision, with a final cast of the result to the target column type. Existing null flags are not modified by this operation, but new null flags are added to mark any illegal operation: if the specified exponent is not negative, all column elements must be not negative, and if the specified exponent is negative, all matrix elements must be positive; column values not fulfilling this condition will be invalidated. If the exponent is 0.0, then any (valid) column element would be assigned the value 1.0.

cpl_error_code cpl_table_column_subtract_constant cpl_table *    table,
const char *    name,
double    value
 

Subtract a constant value from a numerical column.

Parameters:
table  Pointer to table.
name  Column name.
value  Value to subtract.
Returns:
See function cpl_table_column_add_constant().
See the description of the function cpl_table_column_add_constant().

int cpl_table_compare_structures cpl_table *    table1,
cpl_table *    table2
 

Compare the structure of two tables.

Parameters:
table1  Pointer to a table.
table2  Pointer to another table.
Returns:
0 if the tables have the same structure, 1 otherwise.
Two tables have the same structure if they have the same number of columns, with the same names and the same types. The order of the columns is unimportant.

cpl_error_code cpl_table_const_op cpl_table *    table,
const char *    name,
double    value,
int    operation
 

Arithmetic between a numerical column and a constant.

Parameters:
table  Pointer to table.
name  Column name.
value  A scalar.
operation  Operation to perform.
Returns:
CPL_ERROR_NONE on success. If the specified column is not found in the input table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is of type CPL_TYPE_STRING, a CPL_ERROR_INVALID_TYPE is returned. If unsupported operations are specified, a CPL_ERROR_UNSUPPORTED_MODE is returned. If the specified constant is zero, and the specified operation is a division, a CPL_ERROR_DIVISION_BY_ZERO is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. Existing null flags marking invalid column elements are not modified by this operation, but new null flags are added when the result of the operation is indetermined - as for instance in the case of the logarithm of a non-positive number. The table selection flags are always reset. The supported operations are:

  • '+' Addition
  • '-' Subtraction
  • '*' Multiplication
  • '/' Division
  • 'l' Logarithm
  • '^' Power
  • 'e' Exponentiation
When the logarithm or the exponential are computed, the passed constant represents the base of the logarithm or of the exponential. An assertion failure would be generated by specifying a non-positive base for the 'l' or the 'e' operation. All the available operations are in practice carried out by the functions

Refer to the documentation of those functions for more details on the corresponding operation. As an example, the two following calls are equivalent:

   cpl_table_const_op(table, name, 1.23, '^');
   cpl_table_column_power(table, name, 1.23);

cpl_error_code cpl_table_convert_column cpl_table *    table,
const char *    from_name,
const char *    to_name,
cpl_type    type
 

Cast a numeric column to a new numeric type column.

Parameters:
table  Pointer to table.
from_name  Name of table column to cast.
to_name  Name of new table column.
type  Type of new table column.
Returns:
CPL_ERROR_NONE on success. If the specified column does not exist, a CPL_ERROR_DATA_NOT_FOUND is returned. If a column with the new name already exists in the table, a CPL_ERROR_ILLEGAL_OUTPUT is returned. If the accessed column is of type CPL_TYPE_STRING, a CPL_ERROR_INVALID_TYPE is returned.
A new column of the specified type is created, and the content of the given numeric column is cast to the new type. If the input column type is identical to the specified type the column is duplicated as is done by the function cpl_table_duplicate_column().

cpl_error_code cpl_table_copy_data cpl_table *    table,
const char *    name,
double *    data
 

Copy a numerical array to an existing table column.

Parameters:
table  Pointer to table.
name  Name of the table column.
data  Pointer to array of data.
Returns:
CPL_ERROR_NONE on success. If a column with the given name is not found in the table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is not a numerical column, a CPL_ERROR_INVALID_TYPE is returned.
The input data values are physically copied into the specified column, being casted to its specific numerical type according to the C casting rules. Cast to non-numerical columns is not supported. The size of the input array is not checked in any way, and it is expected to match the number of rows assigned to the given table. The pointed data values are all taken as valid: invalid values should be marked using the functions cpl_table_set_null() and cpl_table_fill_column_null().

cpl_error_code cpl_table_copy_data_double cpl_table *    table,
const char *    name,
double *    data
 

Copy existing data to a table double column.

Parameters:
table  Pointer to table.
name  Name of the double column.
data  Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If a column with the given name is not found in the table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the input column is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is returned.
See the description of cpl_table_copy_data_int() for further details.

cpl_error_code cpl_table_copy_data_float cpl_table *    table,
const char *    name,
float *    data
 

Copy existing data to a table float column.

Parameters:
table  Pointer to table.
name  Name of the float column.
data  Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If a column with the given name is not found in the table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the input column is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is returned.
See the description of cpl_table_copy_data_int() for further details.

cpl_error_code cpl_table_copy_data_int cpl_table *    table,
const char *    name,
int *    data
 

Copy existing data to a table integer column.

Parameters:
table  Pointer to table.
name  Name of the integer column.
data  Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If a column with the given name is not found in the table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the input column is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is returned.
The input data values are physically copied to the specified column. The size of the input array is not checked in any way, and it is expected to match the number of rows assigned to the given table. The pointed data values are all taken as valid: invalid values should be marked using the functions cpl_table_set_null() and cpl_table_fill_column_null().

cpl_error_code cpl_table_copy_data_string cpl_table *    table,
const char *    name,
char **    data
 

Copy existing data to a table string column.

Parameters:
table  Pointer to table.
name  Name of the string column.
data  Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If a column with the given name is not found in the table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the input column is not of type CPL_TYPE_STRING, a CPL_ERROR_TYPE_MISMATCH is returned.
See the description of cpl_table_copy_data_int() for further details. In the particular case of a string column, it should be noted that the data are copied in-depth, i.e., also the pointed strings are duplicated. Strings contained in the existing table column are deallocated before being replaced by the new ones.

void cpl_table_delete cpl_table *    table
 

Delete a table.

Parameters:
table  Pointer to table to be deleted.
Returns:
Nothing.
This function deletes a table, releasing all the memory associated to it, including any existing column. If table is NULL, nothing is done.

cpl_error_code cpl_table_delete_column cpl_table *    table,
const char *    name
 

Delete a column from a table.

Parameters:
table  Pointer to table.
name  Name of table column to delete.
Returns:
CPL_ERROR_NONE on success. If the column is not found in table a CPL_ERROR_DATA_NOT_FOUND is returned.
Delete a column from a table. If the column is not found nothing is done and a failure is returned. If the table is left without columns, the selection flags are reset.

cpl_error_code cpl_table_divide_columns cpl_table *    table,
const char *    to_name,
const char *    from_name
 

Divide two numeric table columns.

Parameters:
table  Pointer to table.
to_name  Name of target column.
from_name  Name of column dividing the target column.
Returns:
See cpl_table_add_columns().
The columns are divided element by element, and the result of the division is stored in the target column. The columns types may differ, and in that case the operation would be performed according to the C upcasting rules, with a final cast of the result to the target column type. Also null flags are upgraded: if either or both members of the division are invalid, the result will be invalid too. Underflows and overflows are ignored, but a division by exactly zero results in an invalid column element. The table selection flags are always reset.

cpl_table* cpl_table_duplicate cpl_table *    table
 

Make a copy of a table.

Parameters:
table  Pointer to table.
Returns:
Pointer to the new table.
If the input table is NULL, as in case of any other error, a NULL is returned. The copy operation is done "in depth": columns data are duplicated too, not just their pointers. Also the selection flags of the original table are transferred to the new table.

cpl_error_code cpl_table_duplicate_column cpl_table *    to_table,
const char *    to_name,
cpl_table *    from_table,
const char *    from_name
 

Copy a column from a table to another.

Parameters:
to_table  Table to copy column to.
to_name  New name of copied column.
from_table  Table to copy column from.
from_name  Name of column to copy.
Returns:
CPL_ERROR_NONE on success. If the input tables have not the same number of rows, a CPL_ERROR_INCOMPATIBLE_INPUT is returned. If the specified column does not exist in the source table, a CPL_ERROR_DATA_NOT_FOUND is returned. If a column with the same name already exists in the target table, a CPL_ERROR_ILLEGAL_OUTPUT is returned.
Copy a column from a table to another. The column is physically duplicated. Both tables must have the same number of rows. A column may be duplicated also within the same table. A column with the same name must not exist in the target table.

cpl_error_code cpl_table_erase_segment cpl_table *    table,
int    start,
int    count
 

Delete a table segment.

Parameters:
table  Pointer to table.
start  First row to delete.
count  Number of rows to delete.
Returns:
CPL_ERROR_NONE on success. An attempt to delete all rows causes a CPL_ERROR_ILLEGAL_INPUT to be returned.
A portion of the table data is physically removed. The pointer to column data may change, therefore pointers previously retrieved by calling cpl_table_get_data_int(), cpl_table_get_data_string(), etc., should be discarded. The table selection flags are reset. The specified segment can extend beyond the end of the table, but an attempt to remove all table rows would be flagged as an error because zero length tables are illegal, and the table will not be modified.

cpl_error_code cpl_table_erase_unselected cpl_table *    table
 

Keep just the selected rows of a table.

Parameters:
table  Pointer to table
Returns:
CPL_ERROR_NONE on success. An attempt to delete all table rows causes a CPL_ERROR_ILLEGAL_INPUT to be returned.
A portion of the table data is physically removed. The pointer to column data may change, therefore pointers previously retrieved by calling cpl_table_get_data_int(), cpl_table_get_data_string(), etc., should be discarded. The table selection flags are reset. An attempt to remove all table rows is flagged as an error because zero length tables are illegal, and the table will not be modified.

cpl_table* cpl_table_extract cpl_table *    table,
int    start,
int    count
 

Create a table from a section of another table.

Parameters:
table  Pointer to table.
start  First row to be copied to new table.
count  Number of rows to be copied.
Returns:
Pointer to the new table.
A number of consecutive rows are copied from an input table to a newly created table. The new table will have the same structure of the original table (see function cpl_table_compare_structures() ). Specifying a start beyond the table boundaries, or a non-positive count, would generate an assertion failure. If the sum of start and count goes beyond the end of the input table, rows are copied up to the end. Existing null flags are also transferred to the new table columns, but not the selection flags.

cpl_table* cpl_table_extract_selected cpl_table *    table
 

Create a new table from the selected rows of another table.

Parameters:
table  Pointer to table.
Returns:
Pointer to new table, or NULL in case there are no selected rows in the input table.
A new table is created, containing a copy of all the selected rows of the input table. In the output table all rows are selected.

cpl_error_code cpl_table_fill_column cpl_table *    table,
const char *    name,
int    start,
int    count,
double    value
 

Write a value to a numerical column segment.

Parameters:
table  Pointer to table.
name  Name of table column to access.
start  Position where to begin to write the value.
count  Number of values to write.
value  Value to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is not numerical, a CPL_ERROR_INVALID_TYPE is returned.
Write the same value to a numerical column segment. The value is cast to the type of the accessed column according to the C casting rules. The written values are automatically marked as valid, and the table selection flags are reset. To set a column interval to null use cpl_table_fill_column_null() instead. Specifying a start beyond the table boundaries, or a non-positive count, would generate an assertion failure. If the sum of start and count exceeds the number of elements in the column, the column is filled up to its end.

cpl_error_code cpl_table_fill_column_double cpl_table *    table,
const char *    name,
int    start,
int    count,
double    value
 

Write a value to a double column segment.

Parameters:
table  Pointer to table.
name  Name of table column to access.
start  Position where to begin to write the value.
count  Number of values to write.
value  Value to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is returned.
Write the same value to a double column segment. Internal conversion is not supported, i.e., the accessed column must be of type CPL_TYPE_DOUBLE. For automatic conversion to the accessed column type use the function cpl_table_fill_column(). The written values are automatically marked as valid, and the table selection flags are reset. To set a column interval to null use cpl_table_fill_column_null() instead. Specifying a start beyond the table boundaries, or a non-positive count, would generate an assertion failure. If the sum of start and count exceeds the number of elements in the column, the column is filled up to its end.

cpl_error_code cpl_table_fill_column_float cpl_table *    table,
const char *    name,
int    start,
int    count,
float    value
 

Write a value to a float column segment.

Parameters:
table  Pointer to table.
name  Name of table column to access.
start  Position where to begin to write the value.
count  Number of values to write.
value  Value to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is returned.
Write the same value to a float column segment. Internal conversion is not supported, i.e., the accessed column must be of type CPL_TYPE_FLOAT. For automatic conversion to the accessed column type use the function cpl_table_fill_column(). The written values are automatically marked as valid, and the table selection flags are reset. To set a column interval to null use cpl_table_fill_column_null() instead. Specifying a start beyond the table boundaries, or a non-positive count, would generate an assertion failure. If the sum of start and count exceeds the number of elements in the column, the column is filled up to its end.

cpl_error_code cpl_table_fill_column_int cpl_table *    table,
const char *    name,
int    start,
int    count,
int    value
 

Write a value to an integer column segment.

Parameters:
table  Pointer to table.
name  Name of table column to access.
start  Position where to begin to write the value.
count  Number of values to write.
value  Value to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is returned.
Write the same value to an integer column segment. Internal conversion is not supported, i.e., the accessed column must be of type CPL_TYPE_INT. For automatic conversion to the accessed column type use the function cpl_table_fill_column(). The written values are automatically marked as valid, and the table selection flags are reset. To set a column interval to null use cpl_table_fill_column_null() instead. Specifying a start beyond the table boundaries, or a non-positive count, would generate an assertion failure. If the sum of start and count exceeds the number of elements in the column, the column is filled up to its end.

cpl_error_code cpl_table_fill_column_null cpl_table *    table,
const char *    name,
int    start,
int    count
 

Invalidate a column segment.

Parameters:
table  Pointer to table.
name  Name of table column to access.
start  Position where to begin invalidation.
count  Number of column elements to invalidate.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned.
Flag as null all the column elements in the specified interval. In the case of a string column, the corresponding strings are set free. The table selection flags are always reset. Specifying a start beyond the table boundaries, or a non-positive count, would generate an assertion failure. If the sum of start and count exceeds the number of elements in the column, the column is invalidated up to its end.

cpl_error_code cpl_table_fill_column_string cpl_table *    table,
const char *    name,
int    start,
int    count,
char *    value
 

Write a character string to a string column segment.

Parameters:
table  Pointer to table.
name  Name of table column to access.
start  Position where to begin to write the character string.
count  Number of strings to write.
value  Character string to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the column is not of type CPL_TYPE_STRING, a CPL_ERROR_TYPE_MISMATCH is returned.
Write the same value to a string column segment. Internal conversion is not supported, i.e., the accessed column must be of type CPL_TYPE_STRING. If the input string is not a NULL, it is duplicated for each accessed column element. If the input string is NULL, this call is equivalent to a call to cpl_table_fill_column_null(). The table selection flags are always reset. Specifying a start beyond the table boundaries, or a non-positive count, would generate an assertion failure. If the sum of start and count exceeds the number of elements in the column, the column is filled up to its end.

double cpl_table_get cpl_table *    table,
const char *    name,
int    row,
int *    null
 

Read a value from a numerical column.

Parameters:
table  Pointer to table.
name  Name of table column to be accessed.
row  Position of element to be read.
null  Flag indicating null values, or error condition.
Returns:
Value read. In case of error 0.0 is returned. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set. If a non-numerical column is accessed, a CPL_ERROR_INVALID_TYPE is set.
Read a value from a numerical column. The value read is casted to type double according to the C casting rules. In case of error, or of a null column element, the returned value is always set to 0.0. A null flag may be returned to indicate whether the accessed column element is a null (1) or not (0). The null flag signals also possible error conditions (-1), as specifying a column that is not numerical, or that cannot be found. The passed null flag pointer can also be NULL, and in that case this option will be disabled. Specifying a row beyond the table boundaries would generate an assertion failure.

const char* cpl_table_get_column_format cpl_table *    table,
const char *    name
 

Get the format of a table column.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Format of column, or NULL if no unit can be returned. If the specified column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set.
Return the format of a column, if present. Note that the returned string is a pointer to the column format, not its copy. Its manipulation will directly affect the column format, while changing the column format using cpl_column_set_format() will turn it into garbage. Therefore, if a real copy of a column unit is required, this function should be called as an argument of the function strdup().

const char* cpl_table_get_column_name cpl_table *    table
 

Get table columns names.

Parameters:
table  Pointer to table.
Returns:
Name of a table column.
If this function is not called with a NULL pointer the name of the first table column will be returned. Further calls made with a NULL pointer would return the next columns names, till the end of the list of columns when a NULL would be returned. This function only guarantees that all the table column names would be returned by subsequent calls to this function, but the order in which the column names are returned is undefined. The table structure must not be modified (e.g. by deleting, creating, moving, or renaming columns) between a sequence of calls to cpl_table_get_column_name() related to the same table, or this function behaviour will be undetermined. This function returns a pointer to the table column name, and not to its copy, therefore the pointed string shouldn't be deallocated or manipulated in any way. Its manipulation would directly affect the column name, while changing the column name using cpl_table_rename_column() would turn it into garbage. Therefore, if a real copy of a column name is required, this function should be called as an argument of the function strdup().

cpl_type cpl_table_get_column_type cpl_table *    table,
const char *    name
 

Get the type of a table column.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Column type, or CPL_TYPE_INVALID in case of failure. A failure can occur only if the column is not found, and in that case a CPL_ERROR_DATA_NOT_FOUND is set.
Get the type of a column. If a column with the specified name is not found, CPL_TYPE_INVALID is returned and CPL_ERROR_DATA_NOT_FOUND is set.

const char* cpl_table_get_column_unit cpl_table *    table,
const char *    name
 

Get the unit of a table column.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Unit of column, or NULL if no unit can be returned. If the specified column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set.
Return the unit of a column, if present. Note that the returned string is a pointer to the column unit, not its copy. Its manipulation will directly affect the column unit, while changing the column unit using cpl_column_set_unit() will turn it into garbage. Therefore, if a real copy of a column unit is required, this function should be called as an argument of the function strdup(). If the input column has no unit, or in case of error, a NULL is returned.

double* cpl_table_get_data_double cpl_table *    table,
const char *    name
 

Get a pointer to double column data.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Pointer to double column data, or NULL in case of failure. If the column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set. If the column has not type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is set.
A table column of type CPL_TYPE_DOUBLE includes an array of values of type double. This function returns a pointer to this array. The data buffer elements corresponding to invalid column elements would in general contain garbage. To avoid this, cpl_table_column_code_null_double() should be called just before this function, physically assigning to all the invalid column elements an ad hoc numerical value. See the description of function cpl_table_column_code_null_double() for more details.

Note:
Use at your own risk: direct manipulation of column data rules out any check performed by the table object interface, and may introduce inconsistencies between the information maintained internally, and the actual column data and structure.

float* cpl_table_get_data_float cpl_table *    table,
const char *    name
 

Get a pointer to float column data.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Pointer to float column data, or NULL in case of failure. If the column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set. If the column has not type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is set.
A table column of type CPL_TYPE_FLOAT includes an array of values of type float. This function returns a pointer to this array. The data buffer elements corresponding to invalid column elements would in general contain garbage. To avoid this, cpl_table_column_code_null_float() should be called just before this function, physically assigning to all the invalid column elements an ad hoc numerical value. See the description of function cpl_table_column_code_null_float() for more details.

Note:
Use at your own risk: direct manipulation of column data rules out any check performed by the table object interface, and may introduce inconsistencies between the information maintained internally, and the actual column data and structure.

int* cpl_table_get_data_int cpl_table *    table,
const char *    name
 

Get a pointer to integer column data.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Pointer to integer column data, or NULL in case of failure. If the column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set. If the column has not type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is set.
A cpl_table column of type CPL_TYPE_INT includes an array of values of type int. This function returns a pointer to this array. The data buffer elements corresponding to invalid column elements would in general contain garbage. To avoid this, cpl_table_column_code_null_int() should be called just before this function, physically assigning to all the invalid column elements an ad hoc numerical value. See the description of function cpl_table_column_code_null_int() for more details.

Note:
Use at your own risk: direct manipulation of column data rules out any check performed by the table object interface, and may introduce inconsistencies between the information maintained internally, and the actual column data and structure.

char** cpl_table_get_data_string cpl_table *    table,
const char *    name
 

Get a pointer to string column data.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Pointer to string column data, or NULL in case of failure. If the column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set. If the column has not type CPL_TYPE_STRING, a CPL_ERROR_TYPE_MISMATCH is set.
A table column of type CPL_TYPE_STRING includes an array of values of type char*. This function returns a pointer to this array.

Note:
Use at your own risk: direct manipulation of column data rules out any check performed by the table object interface, and may introduce inconsistencies between the information maintained internally, and the actual column data and structure.

double cpl_table_get_double cpl_table *    table,
const char *    name,
int    row,
int *    null
 

Read a value from a double column.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Position of element to be read.
null  Flag indicating null values, or error condition.
Returns:
Value read. In case of error, or of invalid column element, 0.0 is returned. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is set.
Read a value from a double column. Internal conversion is not provided, i.e., the accessed column must be of type CPL_TYPE_DOUBLE. For automatic conversion (always to type double), use the function cpl_table_get(). In case of error, or of a null column element, the returned value is always set to zero. A null flag may be returned to indicate whether the accessed column element is a null (1) or not (0). The null flag also signals possible error conditions (-1), as specifying a column that is not double, or that cannot be found. The null flag pointer can also be NULL, and in that case this option will be disabled. Specifying a row beyond the table boundaries would generate an assertion failure.

float cpl_table_get_float cpl_table *    table,
const char *    name,
int    row,
int *    null
 

Read a value from a float column.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Position of element to be read.
null  Flag indicating null values, or error condition.
Returns:
Value read. In case of error, or of invalid column element, 0.0 is returned. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is set.
Read a value from a float column. Internal conversion is not provided, i.e., the accessed column must be of type CPL_TYPE_FLOAT. For automatic conversion (always to type double), use the function cpl_table_get(). In case of error, or of a null column element, the returned value is always set to zero. A null flag may be returned to indicate whether the accessed column element is a null (1) or not (0). The null flag also signals possible error conditions (-1), as specifying a column that is not float, or that cannot be found. The null flag pointer can also be NULL, and in that case this option will be disabled. Specifying a row beyond the table boundaries would generate an assertion failure.

int cpl_table_get_int cpl_table *    table,
const char *    name,
int    row,
int *    null
 

Read a value from an integer column.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Position of element to be read.
null  Flag indicating null values, or error condition.
Returns:
Value read. In case of error, or of invalid column element, 0 is returned. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is set.
Read a value from an integer column. Internal conversion is not provided, i.e., the accessed column must be of type CPL_TYPE_INT. For automatic conversion (always to type double), use the function cpl_table_get(). In case of error, or of a null column element, the returned value is always set to zero. A null flag may be returned to indicate whether the accessed column element is a null (1) or not (0). The null flag also signals possible error conditions (-1), as specifying a column that is not integer, or that cannot be found. The null flag pointer can also be NULL, and in that case this option will be disabled. Specifying a row beyond the table boundaries would generate an assertion failure.

int cpl_table_get_ncol cpl_table *    table
 

Get the number of columns in a table.

Parameters:
table  Pointer to table to examine.
Returns:
Number of columns in the table. If a NULL table pointer is passed, 0 is returned and a CPL_ERROR_NULL_INPUT is set.
Get the number of columns in a table. If table is NULL, zero is returned.

int cpl_table_get_nrow cpl_table *    table
 

Get the number of rows in a table.

Parameters:
table  Pointer to table to examine.
Returns:
Number of rows in the table. If a NULL table pointer is passed, 0 is returned and a CPL_ERROR_NULL_INPUT is set.
Get the number of rows in a table. If table is NULL, zero is returned.

const char* cpl_table_get_string cpl_table *    table,
const char *    name,
int    row
 

Read a value from a string column.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Position of element to be read.
Returns:
Pointer to string. In case of error, or of invalid column element, a NULL is returned. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_STRING, a CPL_ERROR_TYPE_MISMATCH is set.
Read a character string from a string column. Internal conversion is not provided, i.e., the accessed column must be of type CPL_TYPE_STRING. In case of error, or of a null column element, a NULL pointer is returned. Specifying a row beyond the table boundaries would generate an assertion failure. Note that the returned string is a pointer to a column element, not its copy. Its manipulation will directly affect that column element, while changing that column element using cpl_table_set_string() will turn it into garbage. Therefore, if a real copy of a string column element is required, this function should be called as the argument of the function strdup().

cpl_error_code cpl_table_insert_segment cpl_table *    table,
int    start,
int    count
 

Insert a segment of null rows into table data.

Parameters:
table  Pointer to table
start  Row where to insert the null segment.
count  Length of the null segment.
Returns:
CPL_ERROR_NONE on success.
Insert a segment of null values in each column. This is different from setting a column data segment to null, as done by cpl_table_fill_column_null(): here a portion of new data is physically inserted. Setting start to a number greater than the column length is legal, and has the effect of appending null rows at the end of the table: this is equivalent to expanding the table using cpl_table_resize(). The pointers to column data values may change, therefore pointers previously retrieved by calling cpl_table_get_data_int(), cpl_table_get_data_string(), etc., should be discarded.

int cpl_table_is_empty cpl_table *    table
 

Check if a table has columns.

Parameters:
table  Pointer to table.
Returns:
0 if table is not empty.
Check if a table has columns.

cpl_table* cpl_table_load char *    filename,
int    xtnum,
int    check_nulls
 

Load a FITS table extension into a new cpl_table.

Parameters:
filename  Name of FITS file with at least one table extension.
xtnum  Number of extension to read, starting from 1.
check_nulls  If set to 0, identified NULL values are not flagged.
Returns:
New table, or NULL in case of failure. If a file with the specified name is not found, a CPL_ERROR_FILE_NOT_FOUND is set. If the input file is not in FITS format, a CPL_ERROR_ILLEGAL_INPUT is set. If the specified extension number is greater than the number of FITS extensions in the file, a CPL_ERROR_ACCESS_OUT_OF_RANGE is set. If the input FITS table has no rows or no columns, a CPL_ERROR_NULL_INPUT is set. Other error codes may be set, even if they are not expected to occur: CPL_ERROR_DATA_NOT_FOUND, and CPL_ERROR_INVALID_TYPE. If such errors are set, they should be reported to the CPL Team.
This routine is based on the qfits routine qfits_table_open() call. The selected FITS file table extension is just read and converted into the cpl_table conventions.

cpl_error_code cpl_table_merge cpl_table *    target_table,
cpl_table *    insert_table,
int    row
 

Merge two tables that have the same structure.

Parameters:
target_table  Target table.
insert_table  Table to be inserted in the target table.
row  Row where to insert the insert table.
Returns:
CPL_ERROR_NONE on success. If the input tables have not the same structure (see function cpl_table_compare_structures() ), a CPL_ERROR_INCOMPATIBLE_INPUT is returned.
Data from the insert_table are duplicated and inserted at the specified position of the target_table. If the specified row is greater than the target table length, the second table will be appended to the target table. The selection flags of the target table are always reset. The pointers to column data in the target table may change, therefore pointers previously retrieved by calling cpl_table_get_data_int(), cpl_table_get_data_string(), etc., should be discarded.

Note:
Two tables have the same structure if they have the same number of columns, with the same names and the same types (the order of the columns is unimportant).

cpl_error_code cpl_table_move_column cpl_table *    to_table,
const char *    name,
cpl_table *    from_table
 

Move a column from a table to another.

Parameters:
to_table  Table to move column to.
name  Name of column to move.
from_table  Table to move column from.
Returns:
CPL_ERROR_NONE on success. If the input tables have not the same number of rows, a CPL_ERROR_INCOMPATIBLE_INPUT is returned. If the specified column does not exist in the source table, a CPL_ERROR_DATA_NOT_FOUND is returned. If a column with the same name already exists in the target table, a CPL_ERROR_ILLEGAL_OUTPUT is returned.
Move a column from a table to another. The tables must have the same number of rows. If the same table is specified as source and as target, an assertion failure would be generated. A column with the same name must not exist in the target table. In case of failure, tables are returned unmodified.

cpl_error_code cpl_table_multiply_columns cpl_table *    table,
const char *    to_name,
const char *    from_name
 

Multiply two numeric table columns.

Parameters:
table  Pointer to table.
to_name  Name of target column.
from_name  Name of column to be multiplied with target column.
Returns:
See cpl_table_add_columns().
The columns are multiplied element by element, and the result of the multiplication is stored in the target column. The columns types may differ, and in that case the operation would be performed according to the C upcasting rules, with a final cast of the result to the target column type. Also null flags are upgraded: if either or both members of the multiplication are invalid, the result will be invalid too. Underflows and overflows are ignored, and the table selection flags are always reset.

cpl_table * cpl_table_new int    length
 

Create an empty table structure.

Parameters:
length  Number of rows in table.
Returns:
Pointer to new table.
This function allocates and initialises memory for a table data container. Zero length tables are illegal, and to specify a non-positive length would generate an assertion failure. A new table is created with no columns, but the size of the columns that will be created is defined once and for all. Furthermore, all of its (still virtual) rows are marked a priori as selected. This should be considered the normal status of a table, as long as no row selection has been applied to it.

cpl_error_code cpl_table_new_column_double cpl_table *    table,
const char *    name
 

Create an empty double column in a table.

Parameters:
table  Pointer to table where to create the new column.
name  Name of the new column.
Returns:
See cpl_table_new_column_int().
This function allocates memory for a new column of type CPL_TYPE_DOUBLE. See the description of cpl_table_new_column_int() for further details.

cpl_error_code cpl_table_new_column_float cpl_table *    table,
const char *    name
 

Create an empty float column in a table.

Parameters:
table  Pointer to table where to create the new column.
name  Name of the new column.
Returns:
See cpl_table_new_column_int().
This function allocates memory for a new column of type CPL_TYPE_FLOAT. See the description of cpl_table_new_column_int() for further details.

cpl_error_code cpl_table_new_column_from_data_double cpl_table *    table,
double *    data,
const char *    name
 

Create in table a new double column obtained from existing data.

Parameters:
table  Pointer to table where to create the new column.
name  Name of the new column.
data  Existing data buffer.
Returns:
See cpl_table_new_column_from_data_int().
This function creates a new column of type CPL_TYPE_DOUBLE that will encapsulate the given data. See the description of cpl_table_new_column_from_data_int() for further details.

cpl_error_code cpl_table_new_column_from_data_float cpl_table *    table,
float *    data,
const char *    name
 

Create in table a new float column obtained from existing data.

Parameters:
table  Pointer to table where to create the new column.
name  Name of the new column.
data  Existing data buffer.
Returns:
See cpl_table_new_column_from_data_int().
This function creates a new column of type CPL_TYPE_FLOAT that will encapsulate the given data. See the description of cpl_table_new_column_from_data_int() for further details.

cpl_error_code cpl_table_new_column_from_data_int cpl_table *    table,
int *    data,
const char *    name
 

Create in table a new integer column obtained from existing data.

Parameters:
table  Pointer to table where to create the new column.
name  Name of the new column.
data  Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If a column with the same name exists already in the table, nothing is done, and a CPL_ERROR_ILLEGAL_OUTPUT is returned.
This function creates a new column of type CPL_TYPE_INT that will encapsulate the given data. To specify NULL pointers would cause an assertion failure. The size of the input data array is not checked in any way, and it is expected to match the number of rows assigned to the given table. The pointed data values are all taken as valid: invalid values should be marked using the functions cpl_table_set_null() and cpl_table_fill_column_null(). The data buffer is not copied, so it should not be deallocated while the table column is still in use: the functions cpl_table_delete_column() or cpl_table_delete() would take care of deallocating it. To avoid problems with the memory managment, the specified data buffer should have been allocated using the functions of the cpl_memory module, and statically allocated data should be avoided too.

cpl_error_code cpl_table_new_column_from_data_string cpl_table *    table,
char **    data,
const char *    name
 

Create in table a new string column obtained from existing data.

Parameters:
table  Pointer to table where to create the new column.
name  Name of the new column.
data  Existing data buffer.
Returns:
See cpl_table_new_column_from_data_int().
This function creates a new column of type CPL_TYPE_STRING that will encapsulate the given data. See the description of cpl_table_new_column_from_data_int() for further details, especially with regard to memory managment. In the specific case of string columns the described restrictions applies also to the single column elements (strings). To deallocate specific column elements the functions cpl_table_set_null() and cpl_table_fill_column_null() should be used.

cpl_error_code cpl_table_new_column_int cpl_table *    table,
const char *    name
 

Create an empty integer column in a table.

Parameters:
table  Pointer to table where to create the new column.
name  Name of the new column.
Returns:
CPL_ERROR_NONE on success. If a column with the same name exists already in the table, nothing is done, and a CPL_ERROR_ILLEGAL_OUTPUT is returned.
This function allocates memory for a new column of type CPL_TYPE_INT. The new column name must be different from any other column name in the table. All the elements of the new column are flagged as nulls.

cpl_error_code cpl_table_new_column_string cpl_table *    table,
const char *    name
 

Create an empty string column in a table.

Parameters:
table  Pointer to table where to create the new column.
name  Name of the new column.
Returns:
See cpl_table_new_column_int().
This function allocates memory for a new column of type CPL_TYPE_STRING. See the description of cpl_table_new_column_int() for further details.

cpl_table* cpl_table_new_from_model cpl_table *    table,
int    length
 

Create a table from a model table.

Parameters:
table  Pointer to the model table.
length  Number of rows in the new table.
Returns:
Pointer to new table.
This function creates a new table having the same column structure (names, types, etc.) of a given model table. All columns in the new table are physically created and initialised to contain just NULL values. length must be positive, or an assertion failure would be generated.

int cpl_table_or_select cpl_table *    table,
const char *    name1,
cpl_table_select_operator    operator,
const char *    name2
 

Select from unselected table rows, by comparing the values of two columns.

Parameters:
table  Pointer to table.
name1  Name of first table column.
operator  Relational operator.
name2  Name of second table column.
Returns:
Number of selected rows, or a negative number in case of error. If a column is not found in the input table, a CPL_ERROR_DATA_NOT_FOUND is returned. If a column is of type CPL_TYPE_STRING, a CPL_ERROR_INVALID_TYPE is returned.
Both columns must be numerical. For all the unselected table rows, the values of the specified columns are compared. The table rows fulfilling the comparison are selected. Invalid elements from either columns never fulfill any comparison by definition. The returned value is the final number of selected rows in the whole table. Allowed relational operators are EQUAL_TO, NOT_EQUAL_TO, GREATER_THAN, NOT_GREATER_THAN, LESS_THAN, NOT_LESS_THAN. See also the function cpl_table_and_select().

int cpl_table_or_select_double cpl_table *    table,
const char *    name,
cpl_table_select_operator    operator,
const double    value
 

Select from unselected table rows, by comparing column values with a constant.

Parameters:
table  Pointer to table.
name  Column name.
operator  Relational operator.
value  Reference value.
Returns:
Number of selected rows, or a negative number in case of error. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is set.
See the description of the function cpl_table_or_select_int().

int cpl_table_or_select_float cpl_table *    table,
const char *    name,
cpl_table_select_operator    operator,
const float    value
 

Select from unselected table rows, by comparing column values with a constant.

Parameters:
table  Pointer to table.
name  Column name.
operator  Relational operator.
value  Reference value.
Returns:
Number of selected rows, or a negative number in case of error. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is set.
See the description of the function cpl_table_or_select_int().

int cpl_table_or_select_int cpl_table *    table,
const char *    name,
cpl_table_select_operator    operator,
const int    value
 

Select from unselected table rows, by comparing column values with a constant.

Parameters:
table  Pointer to table.
name  Column name.
operator  Relational operator.
value  Reference value.
Returns:
Number of selected rows, or a negative number in case of error. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is set. If the accessed column is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is set.
For all the unselected table rows, the values of the specified column are compared with the reference value. The table rows fulfilling the comparison are selected. An invalid element never fulfills any comparison by definition. The returned value is the final number of selected rows in the whole table. Allowed relational operators are EQUAL_TO, NOT_EQUAL_TO, GREATER_THAN, NOT_GREATER_THAN, LESS_THAN, and NOT_LESS_THAN. See also the description of the function cpl_table_and_select_int().

int cpl_table_or_select_nulls cpl_table *    table,
const char *    name
 

Select from unselected table rows all rows with invalid values in one column.

Parameters:
table  Pointer to table.
name  Column name.
Returns:
Number of selected rows, or a negative number in case of error. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is set.
For all the unselected table rows, all the rows containing invalid values at the specified column are selected. The returned value is the final number of selected rows in the whole table. See also the function cpl_table_and_select_nulls().

int cpl_table_or_select_segment cpl_table *    table,
int    start,
int    count
 

Select from unselected rows only those within a table segment.

Parameters:
table  Table to handle.
start  First row of table segment.
count  Length of segment.
Returns:
Number of selected rows, or a negative number in case of error.
All the unselected table rows that are within the specified interval are selected. The returned value is the final number of selected rows in the whole table. See also the function cpl_table_and_select_segment().

int cpl_table_or_select_string cpl_table *    table,
const char *    name,
cpl_table_select_operator    operator,
const char *    string
 

Select from unselected table rows, by comparing column values with a constant.

Parameters:
table  Pointer to table.
name  Column name.
operator  Relational operator.
string  Reference value.
Returns:
See function cpl_table_and_select_string()
For all the unselected table rows, the strings of the specified column are compared with the reference string. The comparison function used is the C standard strcmp(), but in case the relational operators EQUAL_TO or NOT_EQUAL_TO are specified, the comparison string is treated as a regular expression. All table rows fulfilling the comparison are selected. An invalid element never fulfills any comparison by definition. The returned value is the final number of selected rows in the whole table. Allowed relational operators are EQUAL_TO, NOT_EQUAL_TO, GREATER_THAN, NOT_GREATER_THAN, LESS_THAN, and NOT_LESS_THAN. See also the function cpl_table_and_select_string().

void cpl_table_print cpl_table *    table,
int    start,
int    count
 

Print a table.

Parameters:
table  Pointer to table
start  First row to print
count  Number of rows to print
Returns:
Nothing.
All column elements are printed according to the column formats, that may be specified for each table column with the function cpl_table_set_column_format(). The default column formats have been choosen to provide a reasonable printout in most cases. Table rows are counted from 0, and their sequence number is printed at the left of each row. Invalid table elements are represented as a sequence of dashes as wide as the field occupied by the column to which they belong. It is not shown whether a table row is selected or not. Specifying a start beyond the table boundaries, or a non-positive count, would generate an assertion failure. The specified number of rows to print may exceed the table end, and in that case the table would be printed up to its last row.

cpl_error_code cpl_table_prune cpl_table *    table
 

Remove from a table columns and rows just containing invalid elements.

Parameters:
table  Pointer to table.
Returns:
CPL_ERROR_NONE on success. If the input table just contains invalid elements, a CPL_ERROR_ILLEGAL_OUTPUT is returned.
Table columns and table rows just containing invalid elements are deleted from the table. The selection flags are reset. The pointers to data may change, therefore pointers previously retrieved by calling cpl_table_get_data_int(), cpl_table_get_data_string(), etc., should be discarded. If the input table contains just invalid elements nothing is done, and a failure is returned.

cpl_error_code cpl_table_rename_column cpl_table *    table,
const char *    from_name,
const char *    to_name
 

Rename a table column.

Parameters:
table  Pointer to table.
from_name  Name of table column to rename.
to_name  New name of column.
Returns:
CPL_ERROR_NONE on success. If the specified column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If a column with the new name already exists in the table, a CPL_ERROR_ILLEGAL_OUTPUT is returned.
This function is used to change the name of a column. If any NULL pointer is passed, an assertion failure would be generated.

cpl_error_code cpl_table_resize cpl_table *    table,
int    new_length
 

Resize a table to a new number of rows.

Parameters:
table  Pointer to table.
new_length  New number of rows in table.
Returns:
CPL_ERROR_NONE on success.
The contents of the columns will be unchanged up to the lesser of the new and old sizes. If the table is expanded, the extra table rows would just contain invalid elements. The table selection flags are reset. The pointer to column data may change, therefore pointers previously retrieved by calling cpl_table_get_data_int(), cpl_table_get_data_string(), etc. should be discarded. Specifying a non-positive length would generate an assertion failure.

int cpl_table_reverse_selection cpl_table *    table
 

Select unselected table rows, and unselect selected ones.

Parameters:
table  Pointer to table.
Returns:
Number of selected rows.
Select unselected table rows, and unselect selected ones.

cpl_error_code cpl_table_save cpl_table *    table,
cpl_plist   pheader,
cpl_plist   header,
char *    filename,
int    append
 

Save a cpl_table to a FITS file.

Parameters:
table  Input table.
pheader  Primary header entries.
header  Table header entries.
filename  Name of output FITS file.
append  Append flag.
Returns:
CPL_ERROR_NONE on success. If append is not zero and a file with the specified name is not found, a CPL_ERROR_FILE_NOT_FOUND is returned. If this file is not in FITS format, a CPL_ERROR_ILLEGAL_INPUT is returned. If for any reason the file cannot be created, or it's only partially created, a CPL_ERROR_FILE_NOT_CREATED or a CPL_ERROR_FILE_IO are returned. In case the MD5 signature (used to uniquely identify the data) cannot be computed, a CPL_ERROR_ILLEGAL_OUTPUT is returned, but this may be treated just as a warning because at this point a valid FITS file has been already created on disk. A CPL_ERROR_INVALID_TYPE may be returned in the "impossible" case that the cpl_table contained invalid columns, but if such error occurs it should be reported to the CPL Team.
This functions can be used to convert a cpl_table into a binary FITS table extension. If the append flag is set to zero, a new FITS file will be created containing an empty primary array, with just one FITS table extension. An existing FITS file with the same name would be overwritten. If the append flag is not set to zero, a new table extension would be appended to an existing (and writable) FITS file. Two property lists may be passed to this function, both optionally. The first property list, pheader, is just used if the append flag is set to zero, and it is assumed to contain entries for the FITS file primary header. In pheader any property name related to the FITS convention, as SIMPLE, BITPIX, NAXIS, EXTEND, BLOCKED, and END, are ignored: such entries would be written anyway to the primary header and set to some standard values (see the QFITS qfits_table_prim_header_default() function). A DATAMD5 keyword, containing the MD5 signature computed on the whole file, is also added automatically to the primary keyword header. If a NULL pheader is passed, the primary array would be created with just such entries, that are mandatory in any regular FITS file. The second property list, header, is assumed to contain entries for the FITS table extension header. In this property list any property name related to the FITS convention, as XTENSION, BITPIX, NAXIS, PCOUNT, GCOUNT, and END, and to the table structure, as TFIELDS, TTYPEi, TUNITi, TDISPi, TNULLi, TFORMi, would be ignored: such entries are always computed internally, to guarantee their consistency with the actual table structure. A DATE keyword containing the date of table creation in ISO8601 format is also added automatically.

Note:
Invalid strings in columns of type CPL_TYPE_STRING are written to FITS as blanks. Invalid values in columns of type CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE will be written to the FITS file as a NaN. Invalid values in columns of type CPL_TYPE_INT are the only ones that need a specific code to be explicitly assigned to them. This can be realised by calling the function cpl_table_column_code_null_int() for each table column of type CPL_TYPE_INT containing invalid values, just before saving the table to FITS. The numerical values identifying invalid integer column elements are written to the FITS keywords TNULLn (where n is the column sequence number). Beware that if valid column elements have the value identical to the chosen null-code, they will mistakenly be considered invalid in the FITS convention.

cpl_error_code cpl_table_select_all cpl_table *    table
 

Select all table rows.

Parameters:
table  Pointer to table.
Returns:
CPL_ERROR_NONE on success.
The table selection flags are reset, meaning that they are all marked as selected. This is the initial state of any table.

cpl_error_code cpl_table_select_row cpl_table *    table,
int    row
 

Flag a table row as selected.

Parameters:
table  Pointer to table.
row  Row to select.
Returns:
CPL_ERROR_NONE on success.
Flag a table row as selected. Any previous selection is kept. Specifying a row beyond the table boundaries would generate an assertion failure.

cpl_error_code cpl_table_set cpl_table *    table,
const char *    name,
int    row,
double    value
 

Write a value to a numerical table column element.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Position where to write value.
value  Value to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned.
Write a value to a numerical column element. The value is cast to the type of the accessed column according to the C casting rules. The written value is automatically marked as valid, and the table selection flags are reset. To set a column value to null use cpl_table_set_null() instead. Specifying a row beyond the table boundaries would generate an assertion failure.

cpl_error_code cpl_table_set_column_format cpl_table *    table,
const char *    name,
const char *    format
 

Give a new format to a table column.

Parameters:
table  Pointer to table.
name  Column name.
format  New format.
Returns:
CPL_ERROR_NONE on success. If the specified column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned.
The input format string is duplicated before being used as the column format. If format is a NULL pointer, "%s" will be used if the column is of type CPL_TYPE_STRING, "% 1.5e" if the column is of type CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE, and "% 7d" if it is of type CPL_TYPE_INT. The format associated to a column has no effect on any operation performed on columns, and it is used just in the printf() calls made while printing a table using the function cpl_table_print().

cpl_error_code cpl_table_set_column_unit cpl_table *    table,
const char *    name,
const char *    unit
 

Give a new unit to a table column.

Parameters:
table  Pointer to table.
name  Column name.
unit  New unit.
Returns:
CPL_ERROR_NONE on success. If the specified column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned.
The input unit string is duplicated before being used as the column unit. If unit is a NULL pointer, the column will be unitless. The unit associated to a column has no effect on any operation performed on columns, and it must be considered just an optional description of the content of a column.

cpl_error_code cpl_table_set_double cpl_table *    table,
const char *    name,
int    row,
double    value
 

Write a value to a double table column element.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Position where to write value.
value  Value to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the accessed column is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is returned.
Write a value to a double column element. Internal conversion is not supported, i.e., the accessed column must be of type CPL_TYPE_DOUBLE. For automatic conversion to the accessed column type use the function cpl_table_set(). The written value is automatically marked as valid, and the table selection flags are reset. To set a column value to null use cpl_table_set_null() instead. Specifying a row beyond the table boundaries would generate an assertion failure.

cpl_error_code cpl_table_set_float cpl_table *    table,
const char *    name,
int    row,
float    value
 

Write a value to a float table column element.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Position where to write value.
value  Value to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the accessed column is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is returned.
Write a value to a float column element. Internal conversion is not supported, i.e., the accessed column must be of type CPL_TYPE_FLOAT. For automatic conversion to the accessed column type use the function cpl_table_set(). The written value is automatically marked as valid, and the table selection flags are reset. To set a column value to null use cpl_table_set_null() instead. Specifying a row beyond the table boundaries would generate an assertion failure.

cpl_error_code cpl_table_set_int cpl_table *    table,
const char *    name,
int    row,
int    value
 

Write a value to an integer table column element.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Position where to write value.
value  Value to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the accessed column is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is returned.
Write a value to an integer column element. Internal conversion is not supported, i.e., the accessed column must be of type CPL_TYPE_INT. For automatic conversion to the accessed column type use the function cpl_table_set(). The written value is automatically marked as valid, and the table selection flags are reset. To set a column value to null use cpl_table_set_null() instead. Specifying a row beyond the table boundaries would generate an assertion failure.

cpl_error_code cpl_table_set_null cpl_table *    table,
const char *    name,
int    row
 

Flag a column element as invalid.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Row where to write a null.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned.
In the case of a string column, the string is set free and its pointer is set to NULL. For other data types, the corresponding element is flagged internally as invalid. Invalidating any table column element resets the table selection flags. Specifying a row beyond the table boundaries would generate an assertion failure.

cpl_error_code cpl_table_set_string cpl_table *    table,
const char *    name,
int    row,
const char *    value
 

Write a character string to a string table column element.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Position where to write the character string.
value  Character string to write.
Returns:
CPL_ERROR_NONE on success. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is returned. If the accessed column is not of type CPL_TYPE_STRING, a CPL_ERROR_TYPE_MISMATCH is returned.
Copy a character string to a string column element. Internal conversion is not supported, i.e., the accessed column must be of type CPL_TYPE_STRING. The written value can also be a NULL pointer, that is equivalent to a call to cpl_table_set_null(). Writing a value to any table column element resets the table selection flags. Note that the character string is physically copied, therefore the original can be modified without affecting the column content. To "plug" a character string directly into a column element, use the function cpl_table_get_data_string(). Specifying a row beyond the table boundaries would generate an assertion failure.

cpl_error_code cpl_table_shift_column cpl_table *    table,
const char *    name,
int    shift
 

Shift the positions of numeric column values.

Parameters:
table  Pointer to table.
name  Name of table column to shift.
shift  Shift column values by so many rows.
Returns:
CPL_ERROR_NONE on success. If the accessed column is not found, a CPL_ERROR_DATA_NOT_FOUND is returned. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned. If the absolute value of specified shift is greater than the column length, a CPL_ERROR_ILLEGAL_INPUT is returned.
The positions of all column values are shifted by the specified amount. If shift is positive, all values will be moved toward the bottom of the column, otherwise toward its top. In either case as many column elements as the amount of the shift will be left undefined, either at the top or at the bottom of the column according to the direction of the shift. These column elements will be flagged as invalid. This function is applicable just to numeric columns. The selection flags are always reset after this operation.

void cpl_table_show cpl_table *    table
 

Describe the structure and the contents of a table.

Parameters:
table  Pointer to table.
Returns:
Nothing.
This function is mainly intended for debug purposes. Some information about the structure of a table and its contents is printed to terminal:

  • Number of columns, with their names and types
  • Number of invalid elements for each column
  • Number of rows and of selected rows

cpl_error_code cpl_table_sort cpl_table *    table,
char **    names,
int    ncol,
int *    reverse
 

Sort table rows according to columns values.

Parameters:
table  Pointer to table.
names  Names of reference columns.
ncol  Total number of reference columns.
reverse  Array of flags, to indicate if sorting should be reversed.
Returns:
CPL_ERROR_NONE on success. If any of the input columns is not found, a CPL_ERROR_DATA_NOT_FOUND is returned.
A reverse flag may be specified for each reference column given in names, to indicate whether the sorting should be performed according to increasing or decreasing column values. The sorting will be performed by comparing the values of the first reference column; if the compared values are equal, the values from the next column in the list are compared, and so on till the end of the reference columns list. If the reverse flag array is a NULL pointer, sorting according to increasing values is always assumed. If ncol is not positive, or exceeds the total number of columns in the table, an assertion failure is generated.

cpl_error_code cpl_table_subtract_columns cpl_table *    table,
const char *    to_name,
const char *    from_name
 

Subtract two numeric table columns.

Parameters:
table  Pointer to table.
to_name  Name of target column.
from_name  Name of column to be subtracted from target column.
Returns:
See cpl_table_add_columns().
The columns are subtracted element by element, and the result of the subtraction is stored in the target column. The columns types may differ, and in that case the operation would be performed according to the C upcasting rules, with a final cast of the result to the target column type. Also null flags are upgraded: if either or both members of the subtraction are invalid, the result will be invalid too. Underflows and overflows are ignored, and the table selection flags are always reset.

cpl_error_code cpl_table_unselect_all cpl_table *    table
 

Unselect all table rows.

Parameters:
table  Pointer to table.
Returns:
CPL_ERROR_NONE on success.
The table selection flags are all unset, meaning that no table rows are selected.

cpl_error_code cpl_table_unselect_row cpl_table *    table,
int    row
 

Flag a table row as unselected.

Parameters:
table  Pointer to table.
row  Row to unselect.
Returns:
CPL_ERROR_NONE on success.
Flag a table row as unselected. Any previous selection is kept. Specifying a row beyond the table boundaries would generate an assertion failure.

int cpl_table_value_is_null cpl_table *    table,
const char *    name,
int    row
 

Check if a column element is invalid.

Parameters:
table  Pointer to table.
name  Name of table column to access.
row  Column element to examine.
Returns:
1 if the column element is invalid, 0 if not, -1 in case of error. If the given column is not found in table, a CPL_ERROR_DATA_NOT_FOUND is set.
Check if a column element is null flagged. Specifying a row beyond the table boundaries would generate an assertion failure.


Generated on Mon May 24 14:58:05 2004 for Common Pipeline Library Reference Manual by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002