Main Page | Modules | Alphabetical List | Class List | Directories | Class Members

Tables


Functions

cpl_table * cpl_table_new (int)
 Create an empty table structure.
cpl_error_code cpl_table_copy_structure (cpl_table *table, const cpl_table *mtable)
 Give to a table the same structure of another table.
cpl_error_code cpl_table_new_column (cpl_table *table, const char *name, cpl_type type)
 Create an empty column in a table.
cpl_error_code cpl_table_wrap_int (cpl_table *table, int *data, const char *name)
 Create in table a new integer column obtained from existing data.
cpl_error_code cpl_table_wrap_float (cpl_table *table, float *data, const char *name)
 Create in table a new float column obtained from existing data.
cpl_error_code cpl_table_wrap_double (cpl_table *table, double *data, const char *name)
 Create in table a new double column obtained from existing data.
cpl_error_code cpl_table_wrap_string (cpl_table *table, char **data, const char *name)
 Create in table a new string column obtained from existing data.
void * cpl_table_unwrap (cpl_table *table, const char *name)
 Unwrap a table column.
cpl_error_code cpl_table_copy_data_int (cpl_table *table, const char *name, const int *data)
 Copy existing data to a table integer column.
cpl_error_code cpl_table_copy_data_float (cpl_table *table, const char *name, const float *data)
 Copy existing data to a table float column.
cpl_error_code cpl_table_copy_data_double (cpl_table *table, const char *name, const double *data)
 Copy existing data to a table double column.
cpl_error_code cpl_table_copy_data_string (cpl_table *table, const char *name, const char **data)
 Copy existing data to a table string column.
void cpl_table_delete (cpl_table *table)
 Delete a table.
int cpl_table_get_nrow (const cpl_table *table)
 Get the number of rows in a table.
int cpl_table_get_ncol (const cpl_table *table)
 Get the number of columns in a table.
cpl_type cpl_table_get_column_type (const cpl_table *table, const char *name)
 Get the type of a table column.
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.
const char * cpl_table_get_column_unit (const cpl_table *table, const char *name)
 Get the unit of a table column.
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.
const char * cpl_table_get_column_format (const cpl_table *table, const char *name)
 Get the format of a table column.
int * cpl_table_get_data_int (const cpl_table *table, const char *name)
 Get a pointer to integer column data.
float * cpl_table_get_data_float (const cpl_table *table, const char *name)
 Get a pointer to float column data.
double * cpl_table_get_data_double (const cpl_table *table, const char *name)
 Get a pointer to double column data.
char ** cpl_table_get_data_string (const cpl_table *table, const char *name)
 Get a pointer to string column data.
cpl_error_code cpl_table_erase_column (cpl_table *table, const char *name)
 Delete a column from a table.
cpl_error_code cpl_table_erase_window (cpl_table *table, int start, int count)
 Delete a table segment.
cpl_error_code cpl_table_erase_selected (cpl_table *table)
 Delete the selected rows of a table.
cpl_error_code cpl_table_insert_window (cpl_table *table, int start, int count)
 Insert a segment of rows into table data.
int cpl_table_compare_structure (const cpl_table *table1, const cpl_table *table2)
 Compare the structure of two tables.
cpl_error_code cpl_table_insert (cpl_table *target_table, const cpl_table *insert_table, int row)
 Merge two tables.
double cpl_table_get (const cpl_table *table, const char *name, int row, int *null)
 Read a value from a numerical column.
int cpl_table_get_int (const cpl_table *table, const char *name, int row, int *null)
 Read a value from an integer column.
float cpl_table_get_float (const cpl_table *table, const char *name, int row, int *null)
 Read a value from a float column.
double cpl_table_get_double (const cpl_table *table, const char *name, int row, int *null)
 Read a value from a double column.
const char * cpl_table_get_string (const cpl_table *table, const char *name, int row)
 Read a value from a string column.
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.
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.
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.
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.
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.
cpl_error_code cpl_table_set_invalid (cpl_table *table, const char *name, int row)
 Flag a column element as invalid.
cpl_error_code cpl_table_fill_column_window (cpl_table *table, const char *name, int start, int count, double value)
 Write a value to a numerical column segment.
cpl_error_code cpl_table_fill_column_window_int (cpl_table *table, const char *name, int start, int count, int value)
 Write a value to an integer column segment.
cpl_error_code cpl_table_fill_column_window_float (cpl_table *table, const char *name, int start, int count, float value)
 Write a value to a float column segment.
cpl_error_code cpl_table_fill_column_window_double (cpl_table *table, const char *name, int start, int count, double value)
 Write a value to a double column segment.
cpl_error_code cpl_table_fill_column_window_string (cpl_table *table, const char *name, int start, int count, char *value)
 Write a character string to a string column segment.
cpl_error_code cpl_table_set_column_invalid (cpl_table *table, const char *name, int start, int count)
 Invalidate a column segment.
int cpl_table_is_valid (const cpl_table *table, const char *name, int row)
 Check if a column element is valid.
int cpl_table_has_invalid (const cpl_table *table, const char *name)
 Check if a column contains at least one invalid value.
int cpl_table_has_valid (const cpl_table *table, const char *name)
 Check if a column contains at least one valid value.
int cpl_table_count_invalid (const cpl_table *table, const char *name)
 Count number of invalid values in a table column.
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.
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.
cpl_error_code cpl_table_name_column (cpl_table *table, const char *from_name, const char *to_name)
 Rename a table column.
int cpl_table_has_column (const cpl_table *table, const char *name)
 Check if a column with a given name exists.
const char * cpl_table_get_column_name (const cpl_table *table)
 Get table columns names.
cpl_error_code cpl_table_set_size (cpl_table *table, int new_length)
 Resize a table to a new number of rows.
cpl_table * cpl_table_duplicate (const cpl_table *table)
 Make a copy of a table.
cpl_table * cpl_table_extract (const cpl_table *table, int start, int count)
 Create a table from a section of another table.
cpl_error_code cpl_table_cast_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.
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.
cpl_error_code cpl_table_subtract_columns (cpl_table *table, const char *to_name, const char *from_name)
 Subtract two numeric table columns.
cpl_error_code cpl_table_multiply_columns (cpl_table *table, const char *to_name, const char *from_name)
 Multiply two numeric table columns.
cpl_error_code cpl_table_divide_columns (cpl_table *table, const char *to_name, const char *from_name)
 Divide two numeric table columns.
cpl_error_code cpl_table_add_scalar (cpl_table *table, const char *name, double value)
 Add a constant value to a numerical column.
cpl_error_code cpl_table_subtract_scalar (cpl_table *table, const char *name, double value)
 Subtract a constant value from a numerical column.
cpl_error_code cpl_table_multiply_scalar (cpl_table *table, const char *name, double value)
 Multiply a numerical column by a constant.
cpl_error_code cpl_table_divide_scalar (cpl_table *table, const char *name, double value)
 Divide a numerical column by a constant.
cpl_error_code cpl_table_logarithm_column (cpl_table *table, const char *name, double base)
 Compute the logarithm of column values.
cpl_error_code cpl_table_exponential_column (cpl_table *table, const char *name, double base)
 Compute the exponential of column values.
cpl_error_code cpl_table_power_column (cpl_table *table, const char *name, double exponent)
 Compute the power of column values.
double cpl_table_get_column_mean (const cpl_table *table, const char *name)
 Compute the mean value of a numerical column.
double cpl_table_get_column_median (const cpl_table *table, const char *name)
 Compute the median value of a numerical column.
double cpl_table_get_column_stdev (const cpl_table *table, const char *name)
 Find the standard deviation of a table column.
double cpl_table_get_column_max (const cpl_table *table, const char *name)
 Get maximum value in a numerical column.
double cpl_table_get_column_min (const cpl_table *table, const char *name)
 Get minimum value in a numerical column.
cpl_error_code cpl_table_get_column_maxpos (const cpl_table *table, const char *name, int *row)
 Get position of maximum in a numerical column.
cpl_error_code cpl_table_get_column_minpos (const cpl_table *table, const char *name, int *row)
 Get position of minimum in a numerical column.
cpl_error_code cpl_table_erase_invalid_rows (cpl_table *table)
 Remove from a table columns and rows just containing invalid elements.
cpl_error_code cpl_table_erase_invalid (cpl_table *table)
 Remove from a table all columns just containing invalid elements, and then all rows containing at least one invalid element.
cpl_error_code cpl_table_select_row (cpl_table *table, int row)
 Flag a table row as selected.
cpl_error_code cpl_table_select_all (cpl_table *table)
 Select all table rows.
cpl_error_code cpl_table_unselect_row (cpl_table *table, int row)
 Flag a table row as unselected.
cpl_error_code cpl_table_unselect_all (cpl_table *table)
 Unselect all table rows.
void cpl_table_dump_structure (const cpl_table *table, FILE *stream)
 Describe the structure and the contents of a table.
void cpl_table_dump (const cpl_table *table, int start, int count, FILE *stream)
 Print a table.
cpl_error_code cpl_table_shift_column (cpl_table *table, const char *name, int shift)
 Shift the position of numeric column values.
cpl_error_code cpl_table_fill_invalid_int (cpl_table *table, const char *name, int code)
 Write to invalid integer column elements a numeric code.
cpl_error_code cpl_table_fill_invalid_float (cpl_table *table, const char *name, float code)
 Write to invalid float column elements a numeric code.
cpl_error_code cpl_table_fill_invalid_double (cpl_table *table, const char *name, double code)
 Write to invalid double column elements a numeric code.
int cpl_table_and_selected_int (cpl_table *table, const char *name, cpl_table_select_operator operator, int value)
 Select from selected table rows, by comparing integer column values with a constant.
int cpl_table_or_selected_int (cpl_table *table, const char *name, cpl_table_select_operator operator, int value)
 Select from unselected table rows, by comparing integer column values with a constant.
int cpl_table_and_selected_float (cpl_table *table, const char *name, cpl_table_select_operator operator, float value)
 Select from selected table rows, by comparing float column values with a constant.
int cpl_table_or_selected_float (cpl_table *table, const char *name, cpl_table_select_operator operator, float value)
 Select from unselected table rows, by comparing float column values with a constant.
int cpl_table_and_selected_double (cpl_table *table, const char *name, cpl_table_select_operator operator, double value)
 Select from selected table rows, by comparing double column values with a constant.
int cpl_table_or_selected_double (cpl_table *table, const char *name, cpl_table_select_operator operator, double value)
 Select from unselected table rows, by comparing double column values with a constant.
int cpl_table_and_selected_string (cpl_table *table, const char *name, cpl_table_select_operator operator, const char *string)
 Select from selected table rows, by comparing string column values with a character string.
int cpl_table_or_selected_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.
int cpl_table_and_selected_invalid (cpl_table *table, const char *name)
 Select from selected table rows all rows with an invalid value in a specified column.
int cpl_table_or_selected_invalid (cpl_table *table, const char *name)
 Select from unselected table rows all rows with an invalid value in a specified column.
int cpl_table_and_selected_window (cpl_table *table, int start, int count)
 Select from selected rows only those within a table segment.
int cpl_table_or_selected_window (cpl_table *table, int start, int count)
 Select from unselected rows only those within a table segment.
int cpl_table_not_selected (cpl_table *table)
 Select unselected table rows, and unselect selected ones.
int cpl_table_and_selected (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 numerical columns.
int cpl_table_or_selected (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 numerical columns.
int cpl_table_is_selected (cpl_table *table, int row)
 Determine whether a table row is selected or not.
int cpl_table_count_selected (const cpl_table *table)
 Get number of selected rows in given table.
cpl_table * cpl_table_extract_selected (const cpl_table *table)
 Create a new table from the selected rows of another table.
cpl_error_code cpl_table_sort (cpl_table *table, const cpl_propertylist *reflist)
 Sort table rows according to columns values.
cpl_table * cpl_table_load (const char *filename, int xtnum, int check_nulls)
 Load a FITS table extension into a new cpl_table.
cpl_error_code cpl_table_save (const cpl_table *table, const cpl_propertylist *pheader, const cpl_propertylist *header, const char *filename, unsigned mode)
 Save a cpl_table to a FITS file.

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 containing character strings, CPL_TYPE_STRING. A table column is accessed 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". 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. A cpl_table is created with all raw selected, and a column is created with all elements invalidated.

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 set a CPL_ERROR_NULL_INPUT error code, unless differently specified.
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.
Errors:
CPL_ERROR_NULL_INPUT Input table or any column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with any specified name is not found in table.
CPL_ERROR_INVALID_TYPE Any specified column is not numerical.

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 upcasting rules, with a final cast of the result to the target column type. Invalid elements are propagated consistently: if either or both members of the sum are invalid, the result will be invalid too. Underflows and overflows are ignored.

cpl_error_code cpl_table_add_scalar 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.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are are not modified by this operation.

int cpl_table_and_selected 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 numerical columns.

Parameters:
table Pointer to table.
name1 Name of first table column.
operator Relational operator.
name2 Name of second table column.
Returns:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column names are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with any of the specified names is not found in table.
CPL_ERROR_INVALID_TYPE Any of the specified columns is not numerical.

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 CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, CPL_NOT_LESS_THAN. See also the function cpl_table_or_selected().

int cpl_table_and_selected_double cpl_table *  table,
const char *  name,
cpl_table_select_operator  operator,
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:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_DOUBLE.

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 CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, and CPL_NOT_LESS_THAN. If the table has no rows, no error is set, and 0 is returned. See also the function cpl_table_or_selected_double().

int cpl_table_and_selected_float cpl_table *  table,
const char *  name,
cpl_table_select_operator  operator,
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:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_FLOAT.

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 CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, and CPL_NOT_LESS_THAN. If the table has no rows, no error is set, and 0 is returned. See also the function cpl_table_or_selected_float().

int cpl_table_and_selected_int cpl_table *  table,
const char *  name,
cpl_table_select_operator  operator,
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:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_INT.

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 CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, and CPL_NOT_LESS_THAN. If the table has no rows, no error is set, and 0 is returned. See also the function cpl_table_or_selected_int().

int cpl_table_and_selected_invalid cpl_table *  table,
const char *  name
 

Select from selected table rows all rows with an invalid value in a specified column.

Parameters:
table Pointer to table.
name Column name.
Returns:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.

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_selected_invalid().

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

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

Parameters:
table Pointer to table.
name Column name.
operator Relational operator.
string Reference character string.
Returns:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_STRING.
CPL_ERROR_ILLEGAL_INPUT Invalid regular expression.

For all the already selected table rows, the values 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 CPL_EQUAL_TO or CPL_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 CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, and CPL_NOT_LESS_THAN. If the table has no rows, no error is set, and 0 is returned. See also the function cpl_table_or_selected_string().

int cpl_table_and_selected_window 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:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or start is outside the table boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.

All the selected table rows that are outside the specified interval are unselected. If the sum of start and count goes beyond the end of the input table, rows are checked up to the end of the table. See also the function cpl_table_or_selected_window().

cpl_error_code cpl_table_cast_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.
Errors:
CPL_ERROR_NULL_INPUT Input table or any column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified from_name is not found in table.
CPL_ERROR_ILLEGAL_OUTPUT A column with the specified to_name already exists in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.
CPL_ERROR_ILLEGAL_INPUT The specified type is not numerical.

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().

int cpl_table_compare_structure const cpl_table *  table1,
const 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. In case of error, -1 is returned.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.

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 not relevant.

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

Copy existing data to a table double column.

Parameters:
table Pointer to table.
name Name of the column.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_DOUBLE.

See the description of cpl_table_copy_data_int() for details.

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

Copy existing data to a table float column.

Parameters:
table Pointer to table.
name Name of the column.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_FLOAT.

See the description of cpl_table_copy_data_int() for details.

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

Copy existing data to a table integer column.

Parameters:
table Pointer to table.
name Name of the column.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_INT.

The input data values are copied to the specified column. The size of the input array is not checked in any way, and it is expected to be compatible with the number of rows in the given table. The copied data values are all taken as valid: invalid values should be marked using the functions cpl_table_set_invalid() and cpl_table_set_column_invalid().

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

Copy existing data to a table string column.

Parameters:
table Pointer to table.
name Name of the column.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_STRING.

See the description of cpl_table_copy_data_int() for 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.

cpl_error_code cpl_table_copy_structure cpl_table *  table,
const cpl_table *  mtable
 

Give to a table the same structure of another table.

Parameters:
table Pointer to empty table.
mtable Pointer to model table.
Returns:
CPL_ERROR_NONE in case of success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT table contains columns.

This function assignes to a columnless table the same column structure (names, types, etc.) of a given model table. All columns are physically created in the new table, and they are initialised to contain just invalid elements.

int cpl_table_count_invalid const 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 invalid elements in a table column, or -1 in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

Count number of invalid elements in a table column.

int cpl_table_count_selected const cpl_table *  table  ) 
 

Get number of selected rows in given table.

Parameters:
table Pointer to table.
Returns:
Number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.

Get number of selected rows in given table.

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, and no error is set.

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:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or any column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with any specified name is not found in table.
CPL_ERROR_INVALID_TYPE Any specified column is not numerical.

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 using the standard C upcasting rules, with a final cast of the result to the target column type. Invalid elements are propagated consistently: 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 will set an invalid column element.

cpl_error_code cpl_table_divide_scalar 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.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.
CPL_ERROR_DIVISION_BY_ZERO The input value is 0.0.

The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are not modified by this operation.

void cpl_table_dump const cpl_table *  table,
int  start,
int  count,
FILE *  stream
 

Print a table.

Parameters:
table Pointer to table
start First row to print
count Number of rows to print
stream The output stream
Returns:
Nothing.
This function is mainly intended for debug purposes. 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 chosen 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 a warning message, but no error would be set. 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. If the specified stream is NULL, it is set to stdout. The function used for printing is the standard C fprintf().

void cpl_table_dump_structure const cpl_table *  table,
FILE *  stream
 

Describe the structure and the contents of a table.

Parameters:
table Pointer to table.
stream The output stream
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

If the specified stream is NULL, it is set to stdout. The function used for printing is the standard C fprintf().

cpl_table* cpl_table_duplicate const cpl_table *  table  ) 
 

Make a copy of a table.

Parameters:
table Pointer to table.
Returns:
Pointer to the new table, or NULL in case of NULL input, or in case of error.
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 Target table.
to_name New name of copied column.
from_table Source table.
from_name Name of column to copy.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The input tables do not have the same number of rows.
CPL_ERROR_DATA_NOT_FOUND A column with the specified from_name is not found in the source table.
CPL_ERROR_ILLEGAL_OUTPUT A column with the specified to_name already exists in the target table.

Copy a column from a table to another. The column is duplicated. A column may be duplicated also within the same table.

cpl_error_code cpl_table_erase_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.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

Delete a column from a table. If the table is left without columns, the selection flags are reset.

cpl_error_code cpl_table_erase_invalid 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.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.

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 even if no rows or columns are erased. 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.

Note:
If the input table just contains invalid elements, all columns are deleted.

cpl_error_code cpl_table_erase_invalid_rows 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.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.

Table columns and table rows just containing invalid elements are deleted from the table. The selection flags are reset even if no rows or columns are removed. The pointers to data may change, therefore pointers previously retrieved by cpl_table_get_data_int(), cpl_table_get_data_string(), etc., should be discarded.

Note:
If the input table just contains invalid elements, all columns are deleted.

cpl_error_code cpl_table_erase_selected cpl_table *  table  ) 
 

Delete the selected rows of a table.

Parameters:
table Pointer to table
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT table is a NULL pointer.

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.

cpl_error_code cpl_table_erase_window 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.
Errors:
CPL_ERROR_NULL_INPUT table is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has length zero, or start is outside the table range.
CPL_ERROR_ILLEGAL_INPUT count is negative.

A portion of the table data is physically removed. The pointers 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, and in that case rows will be removed up to the end of the table.

cpl_error_code cpl_table_exponential_column 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:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.
CPL_ERROR_ILLEGAL_INPUT The input base is not positive.

Each column element is replaced by its exponential in the specified base. The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are not modified by this operation.

cpl_table* cpl_table_extract const 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, or NULL in case or error.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or start is outside the table boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.

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_structure() ). If the sum of start and count goes beyond the end of the input table, rows are copied up to the end. All the rows of the new table are selected, i.e., existing selection flags are not transferred from the old table to the new one.

cpl_table* cpl_table_extract_selected const 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 of error.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.

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_window 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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or start is outside the table boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

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. To invalidate a column interval use cpl_table_set_column_invalid() instead. If the sum of start and count exceeds the number of table rows, the column is filled up to its end.

cpl_error_code cpl_table_fill_column_window_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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or start is outside the table boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_DOUBLE.

Write the same value to a double column segment. The written values are automatically marked as valid. To invalidate a column interval use cpl_table_set_column_invalid() instead. If the sum of start and count exceeds the number of table rows, the column is filled up to its end.

cpl_error_code cpl_table_fill_column_window_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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or start is outside the table boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_FLOAT.

Write the same value to a float column segment. The written values are automatically marked as valid. To invalidate a column interval use cpl_table_set_column_invalid() instead. If the sum of start and count exceeds the number of table rows, the column is filled up to its end.

cpl_error_code cpl_table_fill_column_window_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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or start is outside the table boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_INT.

Write the same value to an integer column segment. The written values are automatically marked as valid. To invalidate a column interval use cpl_table_set_column_invalid() instead. If the sum of start and count exceeds the number of table rows, the column is filled up to its end.

Note:
For automatic conversion to the accessed column type use the function cpl_table_fill_column_window().

cpl_error_code cpl_table_fill_column_window_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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or start is outside the table boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_STRING.

Write the same value to a string column segment. If the input string is not a NULL pointer, it is duplicated for each accessed column element. If the input string is a NULL pointer, this call is equivalent to a call to cpl_table_set_column_invalid(). If the sum of start and count exceeds the number of rows in the table, the column is filled up to its end.

cpl_error_code cpl_table_fill_invalid_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.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_DOUBLE.

In general, numeric column elements that are flagged as invalid may contain any value, that should not be given any meaning whatsoever. In order to export the column data (using a call to cpl_table_get_data_double() ) to procedures that are external to the CPL column system, it may turn out to be appropriate assigning to all the invalid elements a conventional code value. This code value will supposedly be recognized and handled properly by a given foreign method applied directly to the column data buffer. Note that only existing invalid elements will be coded as indicated: new invalid column elements would still have their actual values left undefined. Also, any further processing of the column would not take care of maintaining the assigned code to a given invalid column element: therefore the code should be applied just before it is actually needed.

Note:
Assigning a code to an invalid element doesn't make it valid.

cpl_error_code cpl_table_fill_invalid_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.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_FLOAT.

In general, numeric column elements that are flagged as invalid may contain any value, that should not be given any meaning whatsoever. In order to export the column data (using a call to cpl_table_get_data_float() ) to procedures that are external to the CPL column system, it may turn out to be appropriate assigning to all the invalid elements a conventional code value. This code value will supposedly be recognized and handled properly by a given foreign method applied directly to the column data buffer. Note that only existing invalid elements will be coded as indicated: new invalid column elements would still have their actual values left undefined. Also, any further processing of the column would not take care of maintaining the assigned code to a given invalid column element: therefore the code should be applied just before it is actually needed.

Note:
Assigning a code to an invalid element doesn't make it valid.

cpl_error_code cpl_table_fill_invalid_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.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_INT.

In general, numeric column elements that are flagged as invalid may contain any value, that should not be given any meaning whatsoever. In order to export the column data (using a call to cpl_table_get_data_int() ) to procedures that are external to the CPL column system, it may turn out to be appropriate assigning to all the invalid elements a conventional code value. This code value will supposedly be recognized and handled properly by a given foreign method applied directly to the column data buffer. Note that only existing invalid elements will be coded as indicated: new invalid column elements would still have their actual values left undefined. Also, any further processing of the column would not take care of maintaining the assigned code to a given invalid column element: therefore the code should be applied just before it is actually needed.

Note:
Assigning a code to an invalid element doesn't make it valid.

double cpl_table_get const 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 invalid table element, or in case of error, 0.0 is returned.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

Rows are counted starting from 0. The null flag is used to indicate whether the accessed table element is valid (0) or invalid (1). The null flag also signals an error condition (-1). The null argument can be left to NULL.

const char* cpl_table_get_column_format const 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 in case of error.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

Return the format of a column. 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 it should be considered read-only, and if a real copy of a column format is required, this function should be called as an argument of the function strdup().

double cpl_table_get_column_max const 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_get_column_mean().
See the description of the function cpl_table_get_column_mean().

cpl_error_code cpl_table_get_column_maxpos const 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.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table, or it just contains invalid elements, or the table has length zero.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

Invalid column values are excluded from the search. The row argument 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_get_column_mean const 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.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table, or it just contains invalid elements, or the table has length zero.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

Invalid column values are excluded from the computation. The table selection flags have no influence on the result.

double cpl_table_get_column_median const 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_get_column_mean().
See the description of the function cpl_table_get_column_mean().

double cpl_table_get_column_min const 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_get_column_mean().
See the description of the function cpl_table_get_column_mean().

cpl_error_code cpl_table_get_column_minpos const 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_get_column_maxpos().
See the description of the function cpl_table_get_column_maxpos().

const char* cpl_table_get_column_name const 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_name_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().

double cpl_table_get_column_stdev const cpl_table *  table,
const char *  name
 

Find the standard deviation of a table column.

Parameters:
table Pointer to table.
name Column name.
Returns:
Standard deviation. See documentation of cpl_table_get_column_mean().
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table, or it just contains invalid elements, or the table has length zero.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

Invalid column values are excluded from the computation of the standard deviation. If just one valid element is found, 0.0 is returned but no error is set. The table selection flags have no influence on the result.

cpl_type cpl_table_get_column_type const 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.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

Get the type of a column.

const char* cpl_table_get_column_unit const 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.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

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 it should be considered read-only, and if a real copy of a column unit is required, this function should be called as an argument of the function strdup().

double* cpl_table_get_data_double const cpl_table *  table,
const char *  name
 

Get a pointer to double column data.

Parameters:
table Pointer to table.
name Column name.
Returns:
Pointer to column data, or NULL if the column has zero length, or in case of failure.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_DOUBLE.

A cpl_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_fill_invalid_double() should be called just before this function, assigning to all the invalid column elements an ad hoc numerical value. See the description of function cpl_table_fill_invalid_double() for further 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 const cpl_table *  table,
const char *  name
 

Get a pointer to float column data.

Parameters:
table Pointer to table.
name Column name.
Returns:
Pointer to column data, or NULL if the column has zero length, or in case of failure.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_FLOAT.

A cpl_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_fill_invalid_float() should be called just before this function, assigning to all the invalid column elements an ad hoc numerical value. See the description of function cpl_table_fill_invalid_float() for further 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 const cpl_table *  table,
const char *  name
 

Get a pointer to integer column data.

Parameters:
table Pointer to table.
name Column name.
Returns:
Pointer to column data, or NULL if the column has zero length, or in case of failure.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_INT.

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_fill_invalid_int() should be called just before this function, assigning to all the invalid column elements an ad hoc numerical value. See the description of function cpl_table_fill_invalid_int() for further 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 const cpl_table *  table,
const char *  name
 

Get a pointer to string column data.

Parameters:
table Pointer to table.
name Column name.
Returns:
Pointer to column data, or NULL if the column has zero length, or in case of failure.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_STRING.

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 const 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:
Double value read. In case of an invalid table element, or in case of error, 0.0 is always returned.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_DOUBLE.

Read a value from a column of type CPL_TYPE_DOUBLE. See the documentation of function cpl_table_get_int().

float cpl_table_get_float const 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:
Float value read. In case of an invalid table element, or in case of error, 0.0 is always returned.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_FLOAT.

Read a value from a column of type CPL_TYPE_FLOAT. See the documentation of function cpl_table_get_int().

int cpl_table_get_int const 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:
Integer value read. In case of an invalid table element, or in case of error, 0 is always returned.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_INT.

Read a value from a column of type CPL_TYPE_INT. If the null flag is a valid pointer, it is used to indicate whether the accessed column element is valid (0) or invalid (1). The null flag also signals an error condition (-1). The null flag pointer can also be NULL, and in that case this option will be disabled. Rows are counted starting from 0.

Note:
For automatic conversion (always to type double), use the function cpl_table_get().

int cpl_table_get_ncol const 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, -1 is returned.
Errors:
CPL_ERROR_NULL_INPUT table is a NULL pointer.

Get the number of columns in a table.

int cpl_table_get_nrow const 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, -1 is returned.
Errors:
CPL_ERROR_NULL_INPUT table is a NULL pointer.

Get the number of rows in a table.

const char* cpl_table_get_string const 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 an invalid column element, or in case of error, a NULL pointer is always returned.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_STRING.

Read a value from a column of type CPL_TYPE_STRING. Rows are counted starting from 0.

Note:
The returned string is a pointer to a table element, not its copy. Its manipulation will directly affect that element, while changing that 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 an argument of the function strdup().

int cpl_table_has_column const 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:
1 if column exists, 0 if column doesn't exist, -1 in case of error.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.

Check if a column with a given name exists in the specified table.

int cpl_table_has_invalid const 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 invalid element, 0 if not, -1 in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

Check if there are invalid elements in a column.

int cpl_table_has_valid const 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, -1 in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

Check if there are valid elements in a column.

cpl_error_code cpl_table_insert cpl_table *  target_table,
const cpl_table *  insert_table,
int  row
 

Merge two tables.

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.
Errors:
CPL_ERROR_NULL_INPUT Any input table is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE row is negative.
CPL_ERROR_INCOMPATIBLE_INPUT The input tables do not have the same structure.

The input tables must have the same structure, as defined by the function cpl_table_compare_structure() . Data from the insert_table are duplicated and inserted at the specified position of the target_table. If the specified row is not less 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.

cpl_error_code cpl_table_insert_window cpl_table *  table,
int  start,
int  count
 

Insert a segment of rows into table data.

Parameters:
table Pointer to table
start Row where to insert the segment.
count Length of the segment.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT table is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE start is negative.
CPL_ERROR_ILLEGAL_INPUT count is negative.

Insert a segment of empty rows, just containing invalid elements. Setting start to a number greater than the column length is legal, and has the effect of appending extra rows at the end of the table: this is equivalent to expanding the table using cpl_table_set_size(). The input column may also have zero length. 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. The table selection flags are reset.

int cpl_table_is_selected cpl_table *  table,
int  row
 

Determine whether a table row is selected or not.

Parameters:
table Pointer to table.
row Table row to check.
Returns:
1 if row is selected, 0 if it is not selected, -1 in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.

Check if a table row is selected.

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

Check if a column element is valid.

Parameters:
table Pointer to table.
name Name of table column to access.
row Column element to examine.
Returns:
1 if the column element is valid, 0 if invalid, -1 in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.

Check if a column element is valid.

cpl_table* cpl_table_load const 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 invalid values are not marked.
Returns:
New table, or NULL in case of failure.
Errors:
CPL_ERROR_NULL_INPUT Input filename is a NULL pointer.
CPL_ERROR_FILE_NOT_FOUND A file named as specified in filename is not found.
CPL_ERROR_BAD_FILE_FORMAT The input file is not in FITS format.
CPL_ERROR_ILLEGAL_INPUT The specified FITS file extension is not a table.
CPL_ERROR_ACCESS_OUT_OF_RANGE xtnum is greater than the number of FITS extensions in the FITS file, or is less than 1.
CPL_ERROR_DATA_NOT_FOUND The FITS table has no rows or no columns.
CPL_ERROR_UNSPECIFIED Generic error condition, that should be reported to the CPL Team.

The selected FITS file table extension is just read and converted into the cpl_table conventions.

cpl_error_code cpl_table_logarithm_column 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:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.
CPL_ERROR_ILLEGAL_INPUT The input base is not positive.

Each column element is replaced by its logarithm in the specified base. The operation is always performed in double precision, with a final cast of the result to the target column type. Invalid elements are not modified by this operation, but zero or negative elements are invalidated by this operation.

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 Target table.
name Name of column to move.
from_table Source table.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The input tables do not have the same number of rows.
CPL_ERROR_ILLEGAL_INPUT Source and target tables are the same table.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in the source table.
CPL_ERROR_ILLEGAL_OUTPUT A column with the same name already exists in the target table.

Move a column from a table to another.

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:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or any column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with any specified name is not found in table.
CPL_ERROR_INVALID_TYPE Any specified column is not numerical.

The columns are multiplied element by element, and the result of the multiplication is stored in the target column. See the documentation of the function cpl_table_add_columns() for further details.

cpl_error_code cpl_table_multiply_scalar 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:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

See the description of the function cpl_table_add_scalar().

cpl_error_code cpl_table_name_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.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the specified from_name is not found in table.
CPL_ERROR_ILLEGAL_OUTPUT A column with the specified to_name already exists in table.

This function is used to change the name of a column.

cpl_table * cpl_table_new int  length  ) 
 

Create an empty table structure.

Parameters:
length Number of rows in table.
Returns:
Pointer to new table, or NULL in case of error.
Errors:
CPL_ERROR_ILLEGAL_INPUT The specified length is negative.

This function allocates and initialises memory for a table data container. A new table is created with no columns, but the size of the columns that will be created is defined in advance, to ensure that all columns will be created with the same length. All table 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 cpl_table *  table,
const char *  name,
cpl_type  type
 

Create an empty column in a table.

Parameters:
table Pointer to table.
name Name of the new column.
type Name of the new column.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_INVALID_TYPE The specified type is not supported.
CPL_ERROR_ILLEGAL_OUTPUT A column with the same name already exists in table.

This function allocates memory for a new column of specified type. The new column name must be different from any other column name in the table. All the elements of the new column are marked as invalid.

int cpl_table_not_selected cpl_table *  table  ) 
 

Select unselected table rows, and unselect selected ones.

Parameters:
table Pointer to table.
Returns:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.

Select unselected table rows, and unselect selected ones.

int cpl_table_or_selected 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 numerical columns.

Parameters:
table Pointer to table.
name1 Name of first table column.
operator Relational operator.
name2 Name of second table column.
Returns:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column names are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with any of the specified names is not found in table.
CPL_ERROR_INVALID_TYPE Any of the specified columns is not numerical.

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. Allowed relational operators are CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, CPL_NOT_LESS_THAN. See also the function cpl_table_and_selected().

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

Select from unselected 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:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_DOUBLE.

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. Allowed relational operators are CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, and CPL_NOT_LESS_THAN. If the table has no rows, no error is set, and 0 is returned. See also the description of the function cpl_table_and_selected_double().

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

Select from unselected 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:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_FLOAT.

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. Allowed relational operators are CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, and CPL_NOT_LESS_THAN. If the table has no rows, no error is set, and 0 is returned. See also the description of the function cpl_table_and_selected_float().

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

Select from unselected 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:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_INT.

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. Allowed relational operators are CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, and CPL_NOT_LESS_THAN. If the table has no rows, no error is set, and 0 is returned. See also the description of the function cpl_table_and_selected_int().

int cpl_table_or_selected_invalid cpl_table *  table,
const char *  name
 

Select from unselected table rows all rows with an invalid value in a specified column.

Parameters:
table Pointer to table.
name Column name.
Returns:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.

For all the unselected table rows, all the rows containing invalid values at the specified column are selected. See also the function cpl_table_and_selected_invalid().

int cpl_table_or_selected_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:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_STRING.
CPL_ERROR_ILLEGAL_INPUT Invalid regular expression.

For all the unselected table rows, the values of the specified column are compared with the reference value. The comparison function used is the C standard strcmp(), but in case the relational operators CPL_EQUAL_TO or CPL_NOT_EQUAL_TO are specified, the comparison string is treated as a regular expression. The table rows fulfilling the comparison are selected. An invalid element never fulfills any comparison by definition. Allowed relational operators are CPL_EQUAL_TO, CPL_NOT_EQUAL_TO, CPL_GREATER_THAN, CPL_NOT_GREATER_THAN, CPL_LESS_THAN, and CPL_NOT_LESS_THAN. If the table has no rows, no error is set, and 0 is returned. See also the description of the function cpl_table_and_selected_string().

int cpl_table_or_selected_window 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:
Current number of selected rows, or a negative number in case of error.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or start is outside the table boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.

All the unselected table rows that are within the specified interval are selected. If the sum of start and count goes beyond the end of the input table, rows are checked up to the end of the table. See also the function cpl_table_and_selected_window().

cpl_error_code cpl_table_power_column 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:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

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. Invalid elements are not modified by this operation, but elements are invalidated at 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 column 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_save const cpl_table *  table,
const cpl_propertylist pheader,
const cpl_propertylist header,
const char *  filename,
unsigned  mode
 

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.
mode Output mode.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or filename are NULL pointers.
CPL_ERROR_FILE_NOT_FOUND While mode is set to CPL_IO_EXTEND, a file named as specified in filename is not found,
CPL_ERROR_BAD_FILE_FORMAT While mode is set to CPL_IO_EXTEND, the specified file is not in FITS format.
CPL_ERROR_FILE_NOT_CREATED The FITS file could not be created.
CPL_ERROR_FILE_IO The FITS file could only partially be created.
CPL_ERROR_ILLEGAL_OUTPUT The MD5 signature (used to uniquely identify the data) could not be computed. This is required for any product of a VLT pipeline.
CPL_ERROR_UNSPECIFIED Generic error condition, that should be reported to the CPL Team.

This function can be used to convert a CPL table into a binary FITS table extension. If the mode is set to CPL_IO_DEFAULT, a new FITS file will be created containing an empty primary array, with just one FITS table extension. An existing (and writable) FITS file with the same name would be overwritten. If the mode flag is set to CPL_IO_EXTEND, a new table extension would be appended to an existing FITS file. Note that also in this case the file must be writable (and do not take for granted that a file is writable just because it was created by the same application, as this depends from the system umask). Two property lists may be passed to this function, both optionally. The first property list, pheader, is just used if the mode is set to CPL_IO_DEFAULT, 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_fill_invalid_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 also 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.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.

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.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.

Flag a table row as selected. Any previous selection is kept.

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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

Write a value to a numerical column element. The value is cast to the accessed column type according to the C casting rules. The written value is automatically marked as valid. To invalidate a column value use cpl_table_set_invalid(). Table rows are counted starting from 0.

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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

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_dump().

cpl_error_code cpl_table_set_column_invalid 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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or start is outside the table boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

All the column elements in the specified interval are invalidated. In the case of a string column, the corresponding strings are set free. If the sum of start and count exceeds the number of rows in the table, the column is invalidated up to its end.

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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_DOUBLE.

Write a value to a table column of type CPL_TYPE_DOUBLE. The written value is automatically marked as valid. To invalidate a column value use cpl_table_set_invalid(). Table rows are counted starting from 0.

Note:
For automatic conversion to the column type, use the function cpl_table_set().

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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_FLOAT.

Write a value to a table column of type CPL_TYPE_FLOAT. The written value is automatically marked as valid. To invalidate a column value use cpl_table_set_invalid(). Table rows are counted starting from 0.

Note:
For automatic conversion to the column type, use the function cpl_table_set().

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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_INT.

Write a value to a table column of type CPL_TYPE_INT. The written value is automatically marked as valid. To invalidate a column value use cpl_table_set_invalid(). Table rows are counted starting from 0.

Note:
For automatic conversion to the column type, use the function cpl_table_set().

cpl_error_code cpl_table_set_invalid 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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

In the case of a string column, the corresponding string is set free and its pointer is set to NULL. For other data types, the corresponding table element is flagged internally as invalid.

cpl_error_code cpl_table_set_size 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.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT The specified new length is negative.

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.

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.
Errors:
CPL_ERROR_NULL_INPUT Input table or name are NULL pointers.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.
CPL_ERROR_TYPE_MISMATCH The specified column is not of type CPL_TYPE_STRING.

Write a string to a table column of type CPL_TYPE_STRING. The written value can also be a NULL pointer, that is equivalent to a call to cpl_table_set_invalid(). Note that the character string is copied, therefore the original can be modified without affecting the table element. To "plug" a character string directly into a table element, use the function cpl_table_get_data_string().

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

Shift the position 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.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.
CPL_ERROR_ILLEGAL_INPUT The absolute value of shift is greater than the column length.

The position of all column values is 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 marked as invalid. This function is applicable just to numeric columns. The selection flags are always reset after this operation.

cpl_error_code cpl_table_sort cpl_table *  table,
const cpl_propertylist reflist
 

Sort table rows according to columns values.

Parameters:
table Pointer to table.
reflist Names of reference columns with corresponding sorting mode.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or reflist are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND Any reference column specified in reflist is not found in table.
CPL_ERROR_ILLEGAL_INPUT The size of reflist exceeds the total number of columns in table, or reflist is empty.
CPL_ERROR_TYPE_MISMATCH The input reflist includes properties of type different from CPL_TYPE_BOOL.

The table rows are sorted according to the values of the specified reference columns. The reference column names are listed in the input reflist, that associates to each reference column a boolean value. If the associated value is FALSE, the table is sorted according to the ascending values of the specified column, otherwise if the associated value is TRUE, the table is sorted according to the descending values of that column. 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. An invalid table element is always treated as if it doesn't fulfill any comparison, i.e., sorting either by increasing or decreasing column values would accumulate invalid elements toward the top of the table.

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:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or any column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with any specified name is not found in table.
CPL_ERROR_INVALID_TYPE Any specified column is not numerical.

The columns are subtracted element by element, and the result of the subtraction is stored in the target column. See the documentation of the function cpl_table_add_columns() for further details.

cpl_error_code cpl_table_subtract_scalar 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:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input table or column name are NULL pointers.
CPL_ERROR_DATA_NOT_FOUND A column with the specified name is not found in table.
CPL_ERROR_INVALID_TYPE The specified column is not numerical.

See the description of the function cpl_table_add_scalar().

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.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.

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.
Errors:
CPL_ERROR_NULL_INPUT Input table is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input table has zero length, or row is outside the table boundaries.

Flag a table row as unselected. Any previous selection is kept.

void* cpl_table_unwrap cpl_table *  table,
const char *  name
 

Unwrap a table column.

Parameters:
table Pointer to table.
name Name of the column.
Returns:
Pointer to internal data buffer, NULL in case of error.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND A column with the given name is not found in table.

This function deallocates all the memory associated to a table column, with the exception of its data buffer. This type of destructor should be used on columns created with the cpl_table_wrap_<type>() constructors, if the data buffer specified then was not allocated using the functions of the cpl_memory module. In such a case, the data buffer should be deallocated separately. See the documentation of the functions cpl_table_wrap_<type>().

cpl_error_code cpl_table_wrap_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.
name Name of the new column.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_ILLEGAL_OUTPUT A column with the same name already exists in table.

This function creates a new column of type CPL_TYPE_DOUBLE that will encapsulate the given data. See the description of cpl_table_wrap_int() for further details.

cpl_error_code cpl_table_wrap_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.
name Name of the new column.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_ILLEGAL_OUTPUT A column with the same name already exists in table.

This function creates a new column of type CPL_TYPE_FLOAT that will encapsulate the given data. See the description of cpl_table_wrap_int() for further details.

cpl_error_code cpl_table_wrap_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.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_ILLEGAL_OUTPUT A column with the same name already exists in table.

This function creates a new column of type CPL_TYPE_INT that will encapsulate the given data. 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_invalid() and cpl_table_set_column_invalid(). The data buffer is not copied, so it should not be deallocated while the table column is still in use: the functions cpl_table_erase_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. If this is not possible, then the function cpl_table_unwrap() should be used on that column before destroying the table that contains it.

cpl_error_code cpl_table_wrap_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.
name Name of the new column.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any argument is a NULL pointer.
CPL_ERROR_ILLEGAL_OUTPUT A column with the same name already exists in table.

This function creates a new column of type CPL_TYPE_STRING that will encapsulate the given data. See the description of cpl_table_wrap_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_invalid() and cpl_table_set_column_invalid() should be used.


Generated on Mon Sep 26 14:38:18 2005 for Common Pipeline Library Reference Manual by  doxygen 1.4.1