Loading...
Searching...
No Matches
Tables

## Functions

cpl_error_code | cpl_table_abs_column (cpl_table *table, const char *name)
| Compute the absolute value of column values.
cpl_error_code | cpl_table_add_columns (cpl_table *table, const char *to_name, const char *from_name)
| Add the values of two numeric or complex table columns.
cpl_error_code | cpl_table_add_scalar (cpl_table *table, const char *name, double value)
| Add a constant value to a numerical or complex column.
cpl_error_code | cpl_table_add_scalar_complex (cpl_table *table, const char *name, double complex value)
| Add a constant complex value to a numerical or complex column.
cpl_size | 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.
cpl_size | 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.
cpl_size | cpl_table_and_selected_double_complex (cpl_table *table, const char *name, cpl_table_select_operator operator, double complex value)
| Select from selected table rows, by comparing double complex column values with a complex constant.
cpl_size | 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.
cpl_size | cpl_table_and_selected_float_complex (cpl_table *table, const char *name, cpl_table_select_operator operator, float complex value)
| Select from selected table rows, by comparing float complex column values with a complex constant.
cpl_size | 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.
cpl_size | 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.
cpl_size | cpl_table_and_selected_long (cpl_table *table, const char *name, cpl_table_select_operator operator, long value)
| Select from selected table rows, by comparing long column values with a constant.
cpl_size | cpl_table_and_selected_long_long (cpl_table *table, const char *name, cpl_table_select_operator operator, long long value)
| Select from selected table rows, by comparing long long column values with a constant.
cpl_size | 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.
cpl_size | cpl_table_and_selected_window (cpl_table *table, cpl_size start, cpl_size count)
| Select from selected rows only those within a table segment.
cpl_error_code | cpl_table_arg_column (cpl_table *table, const char *name)
| Compute the phase angle value of table column elements.
cpl_error_code | cpl_table_cast_column (cpl_table *table, const char *from_name, const char *to_name, cpl_type type)
| Cast a numeric or complex column to a new numeric or complex type column.
int | cpl_table_compare_structure (const cpl_table *table1, const cpl_table *table2)
| Compare the structure of two tables.
cpl_error_code | cpl_table_conjugate_column (cpl_table *table, const char *name)
| Compute the complex conjugate of column values.
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_double_complex (cpl_table *table, const char *name, const double complex *data)
| Copy existing data to a table double complex 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_float_complex (cpl_table *table, const char *name, const float complex *data)
| Copy existing data to a table float complex 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_long (cpl_table *table, const char *name, const long *data)
| Copy existing data to a table long column.
cpl_error_code | cpl_table_copy_data_long_long (cpl_table *table, const char *name, const long long *data)
| Copy existing data to a table long long 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.
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_size | cpl_table_count_invalid (const cpl_table *table, const char *name)
| Count number of invalid values in a table column.
cpl_size | cpl_table_count_selected (const cpl_table *table)
| Get number of selected rows in given table.
void | cpl_table_delete (cpl_table *table)
| Delete a table.
cpl_error_code | cpl_table_divide_columns (cpl_table *table, const char *to_name, const char *from_name)
| Divide two numeric or complex table columns.
cpl_error_code | cpl_table_divide_scalar (cpl_table *table, const char *name, double value)
| Divide a numerical or complex column by a constant.
cpl_error_code | cpl_table_divide_scalar_complex (cpl_table *table, const char *name, double complex value)
| Divide a numerical or complex column by a complex constant.
void | cpl_table_dump (const cpl_table *table, cpl_size start, cpl_size count, FILE *stream)
| Print a table.
void | cpl_table_dump_structure (const cpl_table *table, FILE *stream)
| Describe the structure and the contents of a table.
cpl_table * | cpl_table_duplicate (const cpl_table *table)
| Make a copy of a table.
cpl_error_code | cpl_table_duplicate_column (cpl_table *to_table, const char *to_name, const cpl_table *from_table, const char *from_name)
| Copy a column from a table to another.
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_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_erase_invalid_rows (cpl_table *table)
| Remove from a table columns and rows just containing invalid elements.
cpl_error_code | cpl_table_erase_selected (cpl_table *table)
| Delete the selected rows of a table.
cpl_error_code | cpl_table_erase_window (cpl_table *table, cpl_size start, cpl_size count)
| Delete a table segment.
cpl_error_code | cpl_table_exponential_column (cpl_table *table, const char *name, double base)
| Compute the exponential of column values.
cpl_table * | cpl_table_extract (const cpl_table *table, cpl_size start, cpl_size count)
| Create a table from a section of another 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_fill_column_window (cpl_table *table, const char *name, cpl_size start, cpl_size count, double value)
| Write a value to a numerical column segment.
cpl_error_code | cpl_table_fill_column_window_array (cpl_table *table, const char *name, cpl_size start, cpl_size count, const cpl_array *array)
| Write an array to an array column segment.
cpl_error_code | cpl_table_fill_column_window_complex (cpl_table *table, const char *name, cpl_size start, cpl_size count, double complex value)
| Write a value to a complex column segment.
cpl_error_code | cpl_table_fill_column_window_double (cpl_table *table, const char *name, cpl_size start, cpl_size count, double value)
| Write a value to a double column segment.
cpl_error_code | cpl_table_fill_column_window_double_complex (cpl_table *table, const char *name, cpl_size start, cpl_size count, double complex value)
| Write a value to a double complex column segment.
cpl_error_code | cpl_table_fill_column_window_float (cpl_table *table, const char *name, cpl_size start, cpl_size count, float value)
| Write a value to a float column segment.
cpl_error_code | cpl_table_fill_column_window_float_complex (cpl_table *table, const char *name, cpl_size start, cpl_size count, float complex value)
| Write a value to a float complex column segment.
cpl_error_code | cpl_table_fill_column_window_int (cpl_table *table, const char *name, cpl_size start, cpl_size count, int value)
| Write a value to an integer column segment.
cpl_error_code | cpl_table_fill_column_window_long (cpl_table *table, const char *name, cpl_size start, cpl_size count, long value)
| Write a value to an long column segment.
cpl_error_code | cpl_table_fill_column_window_long_long (cpl_table *table, const char *name, cpl_size start, cpl_size count, long long value)
| Write a value to an long long column segment.
cpl_error_code | cpl_table_fill_column_window_string (cpl_table *table, const char *name, cpl_size start, cpl_size count, const char *value)
| Write a character string to a string column segment.
cpl_error_code | cpl_table_fill_invalid_double (cpl_table *table, const char *name, double code)
| Write a numerical value to invalid double column elements.
cpl_error_code | cpl_table_fill_invalid_double_complex (cpl_table *table, const char *name, double complex code)
| Write a numerical value to invalid double complex column elements.
cpl_error_code | cpl_table_fill_invalid_float (cpl_table *table, const char *name, float code)
| Write a numerical value to invalid float column elements.
cpl_error_code | cpl_table_fill_invalid_float_complex (cpl_table *table, const char *name, float complex code)
| Write a numerical value to invalid float complex column elements.
cpl_error_code | cpl_table_fill_invalid_int (cpl_table *table, const char *name, int code)
| Write a numerical value to invalid integer column elements.
cpl_error_code | cpl_table_fill_invalid_long (cpl_table *table, const char *name, long code)
| Write a numerical value to invalid long column elements.
cpl_error_code | cpl_table_fill_invalid_long_long (cpl_table *table, const char *name, long long code)
| Write a numerical value to invalid long long column elements.
double | cpl_table_get (const cpl_table *table, const char *name, cpl_size row, int *null)
| Read a value from a numerical column.
const cpl_array * | cpl_table_get_array (const cpl_table *table, const char *name, cpl_size row)
| Read an array from an array column.
cpl_size | cpl_table_get_column_depth (const cpl_table *table, const char *name)
| Get the depth of a table column.
cpl_size | cpl_table_get_column_dimension (const cpl_table *table, const char *name, cpl_size indx)
| Get size of one dimension of a table column of arrays.
cpl_size | cpl_table_get_column_dimensions (const cpl_table *table, const char *name)
| Get the number of dimensions of a table column of arrays.
const char * | cpl_table_get_column_format (const cpl_table *table, const char *name)
| Get the format of a table column.
double | cpl_table_get_column_max (const cpl_table *table, const char *name)
| Get maximum value in a numerical column.
cpl_error_code | cpl_table_get_column_maxpos (const cpl_table *table, const char *name, cpl_size *row)
| Get position of maximum in a numerical column.
double | cpl_table_get_column_mean (const cpl_table *table, const char *name)
| Compute the mean value of a numerical column.
double complex | cpl_table_get_column_mean_complex (const cpl_table *table, const char *name)
| Compute the mean value of a numerical or complex 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_min (const cpl_table *table, const char *name)
| Get minimum value in a numerical column.
cpl_error_code | cpl_table_get_column_minpos (const cpl_table *table, const char *name, cpl_size *row)
| Get position of minimum in a numerical column.
const char * | cpl_table_get_column_name (const cpl_table *table)
| Get table columns names.
cpl_array * | cpl_table_get_column_names (const cpl_table *table)
| Get table columns names.
double | cpl_table_get_column_stdev (const cpl_table *table, const char *name)
| Find the standard deviation of a table column.
cpl_type | cpl_table_get_column_type (const cpl_table *table, const char *name)
| Get the type of a table column.
const char * | cpl_table_get_column_unit (const cpl_table *table, const char *name)
| Get the unit of a table column.
double complex | cpl_table_get_complex (const cpl_table *table, const char *name, cpl_size row, int *null)
| Read a value from a complex column.
cpl_array ** | cpl_table_get_data_array (cpl_table *table, const char *name)
| Get a pointer to array column data.
const cpl_array ** | cpl_table_get_data_array_const (const cpl_table *table, const char *name)
| Get a pointer to array column data.
double * | cpl_table_get_data_double (cpl_table *table, const char *name)
| Get a pointer to double column data.
double complex * | cpl_table_get_data_double_complex (cpl_table *table, const char *name)
| Get a pointer to double complex column data.
const double complex * | cpl_table_get_data_double_complex_const (const cpl_table *table, const char *name)
| Get a pointer to constant double complex column data.
const double * | cpl_table_get_data_double_const (const cpl_table *table, const char *name)
| Get a pointer to constant double column data.
float * | cpl_table_get_data_float (cpl_table *table, const char *name)
| Get a pointer to float column data.
float complex * | cpl_table_get_data_float_complex (cpl_table *table, const char *name)
| Get a pointer to float complex column data.
const float complex * | cpl_table_get_data_float_complex_const (const cpl_table *table, const char *name)
| Get a pointer to constant float complex column data.
const float * | cpl_table_get_data_float_const (const cpl_table *table, const char *name)
| Get a pointer to constant float column data.
int * | cpl_table_get_data_int (cpl_table *table, const char *name)
| Get a pointer to integer column data.
const int * | cpl_table_get_data_int_const (const cpl_table *table, const char *name)
| Get a pointer to constant integer column data.
long * | cpl_table_get_data_long (cpl_table *table, const char *name)
| Get a pointer to long column data.
const long * | cpl_table_get_data_long_const (const cpl_table *table, const char *name)
| Get a pointer to constant long column data.
long long * | cpl_table_get_data_long_long (cpl_table *table, const char *name)
| Get a pointer to long long column data.
const long long * | cpl_table_get_data_long_long_const (const cpl_table *table, const char *name)
| Get a pointer to constant long long column data.
char ** | cpl_table_get_data_string (cpl_table *table, const char *name)
| Get a pointer to string column data.
const char ** | cpl_table_get_data_string_const (const cpl_table *table, const char *name)
| Get a pointer to constant string column data.
double | cpl_table_get_double (const cpl_table *table, const char *name, cpl_size row, int *null)
| Read a value from a double column.
double complex | cpl_table_get_double_complex (const cpl_table *table, const char *name, cpl_size row, int *null)
| Read a value from a double complex column.
float | cpl_table_get_float (const cpl_table *table, const char *name, cpl_size row, int *null)
| Read a value from a float column.
float complex | cpl_table_get_float_complex (const cpl_table *table, const char *name, cpl_size row, int *null)
| Read a value from a float complex column.
int | cpl_table_get_int (const cpl_table *table, const char *name, cpl_size row, int *null)
| Read a value from an integer column.
long | cpl_table_get_long (const cpl_table *table, const char *name, cpl_size row, int *null)
| Read a value from a long column.
long long | cpl_table_get_long_long (const cpl_table *table, const char *name, cpl_size row, int *null)
| Read a value from a long long column.
cpl_size | cpl_table_get_ncol (const cpl_table *table)
| Get the number of columns in a table.
cpl_size | cpl_table_get_nrow (const cpl_table *table)
| Get the number of rows in a table.
const char * | cpl_table_get_string (const cpl_table *table, const char *name, cpl_size row)
| Read a value from a string column.
int | cpl_table_has_column (const cpl_table *table, const char *name)
| Check if a column with a given name exists.
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.
cpl_error_code | cpl_table_imag_column (cpl_table *table, const char *name)
| Compute the imaginary part value of table column elements.
cpl_error_code | cpl_table_insert (cpl_table *target_table, const cpl_table *insert_table, cpl_size row)
| Merge two tables.
cpl_error_code | cpl_table_insert_window (cpl_table *table, cpl_size start, cpl_size count)
| Insert a segment of rows into table data.
int | cpl_table_is_selected (const cpl_table *table, cpl_size row)
| Determine whether a table row is selected or not.
int | cpl_table_is_valid (const cpl_table *table, const char *name, cpl_size row)
| 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.
cpl_table * | cpl_table_load_window (const char *filename, int xtnum, int check_nulls, const cpl_array *selcol, cpl_size firstrow, cpl_size nrow)
| Load part of a FITS table extension into a new cpl_table.
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_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_multiply_columns (cpl_table *table, const char *to_name, const char *from_name)
| Multiply two numeric or complex table columns.
cpl_error_code | cpl_table_multiply_scalar (cpl_table *table, const char *name, double value)
| Multiply a numerical or complex column by a constant.
cpl_error_code | cpl_table_multiply_scalar_complex (cpl_table *table, const char *name, double complex value)
| Multiply a numerical or complex column by a complex constant.
cpl_error_code | cpl_table_name_column (cpl_table *table, const char *from_name, const char *to_name)
| Rename a table column.
cpl_table * | cpl_table_new (cpl_size length)
| Create an empty table structure.
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_new_column_array (cpl_table *table, const char *name, cpl_type type, cpl_size depth)
| Create an empty column of arrays in a table.
cpl_size | cpl_table_not_selected (cpl_table *table)
| Select unselected table rows, and unselect selected ones.
cpl_size | 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.
cpl_size | 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.
cpl_size | cpl_table_or_selected_double_complex (cpl_table *table, const char *name, cpl_table_select_operator operator, double complex value)
| Select from unselected table rows, by comparing double complex column values with a complex constant.
cpl_size | 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.
cpl_size | cpl_table_or_selected_float_complex (cpl_table *table, const char *name, cpl_table_select_operator operator, float complex value)
| Select from unselected table rows, by comparing float complex column values with a complex constant.
cpl_size | 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.
cpl_size | 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.
cpl_size | cpl_table_or_selected_long (cpl_table *table, const char *name, cpl_table_select_operator operator, long value)
| Select from unselected table rows, by comparing long column values with a constant.
cpl_size | cpl_table_or_selected_long_long (cpl_table *table, const char *name, cpl_table_select_operator operator, long long value)
| Select from unselected table rows, by comparing long long column values with a constant.
cpl_size | 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.
cpl_size | cpl_table_or_selected_window (cpl_table *table, cpl_size start, cpl_size count)
| Select from unselected rows only those within a table segment.
cpl_error_code | cpl_table_power_column (cpl_table *table, const char *name, double exponent)
| Compute the power of numerical column values.
cpl_error_code | cpl_table_real_column (cpl_table *table, const char *name)
| Compute the real part value of table column elements.
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.
cpl_error_code | cpl_table_select_all (cpl_table *table)
| Select all table rows.
cpl_error_code | cpl_table_select_row (cpl_table *table, cpl_size row)
| Flag a table row as selected.
cpl_error_code | cpl_table_set (cpl_table *table, const char *name, cpl_size row, double value)
| Write a value to a numerical table column element.
cpl_error_code | cpl_table_set_array (cpl_table *table, const char *name, cpl_size row, const cpl_array *array)
| Write an array to an array table column element.
cpl_error_code | cpl_table_set_column_depth (cpl_table *table, const char *name, cpl_size depth)
| Modify depth of a column of arrays.
cpl_error_code | cpl_table_set_column_dimensions (cpl_table *table, const char *name, const cpl_array *dimensions)
| Set the dimensions of a table column of arrays.
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.
cpl_error_code | cpl_table_set_column_invalid (cpl_table *table, const char *name, cpl_size start, cpl_size count)
| Invalidate a column segment.
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.
cpl_error_code | cpl_table_set_complex (cpl_table *table, const char *name, cpl_size row, double complex value)
| Write a complex value to a complex numerical table column element.
cpl_error_code | cpl_table_set_double (cpl_table *table, const char *name, cpl_size row, double value)
| Write a value to a double table column element.
cpl_error_code | cpl_table_set_double_complex (cpl_table *table, const char *name, cpl_size row, double complex value)
| Write a value to a double complex table column element.
cpl_error_code | cpl_table_set_float (cpl_table *table, const char *name, cpl_size row, float value)
| Write a value to a float table column element.
cpl_error_code | cpl_table_set_float_complex (cpl_table *table, const char *name, cpl_size row, float complex value)
| Write a value to a float complex table column element.
cpl_error_code | cpl_table_set_int (cpl_table *table, const char *name, cpl_size row, int value)
| Write a value to an integer table column element.
cpl_error_code | cpl_table_set_invalid (cpl_table *table, const char *name, cpl_size row)
| Flag a column element as invalid.
cpl_error_code | cpl_table_set_long (cpl_table *table, const char *name, cpl_size row, long value)
| Write a value to an long table column element.
cpl_error_code | cpl_table_set_long_long (cpl_table *table, const char *name, cpl_size row, long long value)
| Write a value to an long long table column element.
cpl_error_code | cpl_table_set_size (cpl_table *table, cpl_size new_length)
| Resize a table to a new number of rows.
cpl_error_code | cpl_table_set_string (cpl_table *table, const char *name, cpl_size row, const char *value)
| Write a character string to a string table column element.
cpl_error_code | cpl_table_shift_column (cpl_table *table, const char *name, cpl_size shift)
| Shift the position of numeric or complex column values.
cpl_error_code | cpl_table_sort (cpl_table *table, const cpl_propertylist *reflist)
| Sort table rows according to columns values.
cpl_error_code | cpl_table_subtract_columns (cpl_table *table, const char *to_name, const char *from_name)
| Subtract two numeric or complex table columns.
cpl_error_code | cpl_table_subtract_scalar (cpl_table *table, const char *name, double value)
| Subtract a constant value from a numerical or complex column.
cpl_error_code | cpl_table_subtract_scalar_complex (cpl_table *table, const char *name, double complex value)
| Subtract a constant complex value from a numerical or complex column.
cpl_error_code | cpl_table_unselect_all (cpl_table *table)
| Unselect all table rows.
cpl_error_code | cpl_table_unselect_row (cpl_table *table, cpl_size row)
| Flag a table row as unselected.
void * | cpl_table_unwrap (cpl_table *table, const char *name)
| Unwrap a table column.
cpl_array * | cpl_table_where_selected (const cpl_table *table)
| Get array of indexes to selected table rows.
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_double_complex (cpl_table *table, double complex *data, const char *name)
| Create in table a new double complex column 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_float_complex (cpl_table *table, float complex *data, const char *name)
| Create in table a new float complex column obtained from existing data.
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_long (cpl_table *table, long *data, const char *name)
| Create in table a new long column obtained from existing data.
cpl_error_code | cpl_table_wrap_long_long (cpl_table *table, long long *data, const char *name)
| Create in table a new long long 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.

## 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`. Moreover, it is possible to define columns of arrays, i.e. columns whose elements are arrays of all the basic types listed above. Within the same column all arrays must have the same type and the same length.

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 rows 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_table_abs_column()

cpl_error_code cpl_table_abs_column | ( | cpl_table * | table,
|  | const char * | name )

Compute the absolute value of column values.

Parameters

  table | Pointer to table.
  name | Table column name.

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, or has type array.

Each column element is replaced by its absolute value. Invalid elements are not modified by this operation. If the column is complex, its type will be turned to real (CPL_TYPE_FLOAT_COMPLEX will be changed into CPL_TYPE_FLOAT, and CPL_TYPE_DOUBLE_COMPLEX will be changed into CPL_TYPE_DOUBLE), and any pointer retrieved by calling `cpl_table_get_data_float_complex()` and `cpl_array_get_data_double_complex()` should be discarded.

References CPL_ERROR_NONE, cpl_table_get_column_type(), and CPL_TYPE_COMPLEX.

## cpl_table_add_columns()

cpl_error_code cpl_table_add_columns | ( | cpl_table * | table,
|  | const char * | to_name,
|  | const char * | from_name )

Add the values of two numeric or complex 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 neither numerical nor complex, or it is an array column.

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.

References CPL_ERROR_NONE.

## cpl_table_add_scalar()

cpl_error_code cpl_table_add_scalar | ( | cpl_table * | table,
|  | const char * | name,
|  | double | value )

Add a constant value to a numerical or complex 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 neither numerical nor complex, or it is an array column.

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.

References CPL_ERROR_NONE.

## cpl_table_add_scalar_complex()

cpl_error_code cpl_table_add_scalar_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | double complex | value )

Add a constant complex value to a numerical or complex 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 neither numerical nor complex, or it is an array column.

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.

References CPL_ERROR_NONE.

## cpl_table_and_selected()

cpl_size 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 | Invalid types for comparison.

Either both columns must be numerical, or they both must be strings. The comparison between strings is lexicographical. Comparison between complex types and array types are not supported.

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

References CPL_ERROR_INVALID_TYPE, cpl_table_get_nrow(), cpl_table_unselect_all(), cpl_table_unselect_row(), CPL_TYPE_COMPLEX, CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT, CPL_TYPE_LONG, CPL_TYPE_LONG_LONG, CPL_TYPE_POINTER, and CPL_TYPE_STRING.

## cpl_table_and_selected_double()

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

References cpl_table_get_nrow(), cpl_table_unselect_all(), cpl_table_unselect_row(), and CPL_TYPE_DOUBLE.

## cpl_table_and_selected_double_complex()

cpl_size cpl_table_and_selected_double_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_table_select_operator | operator,
|  | double complex | value )

Select from selected table rows, by comparing double complex column values with a complex 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_COMPLEX.
  CPL_ERROR_ILLEGAL_INPUT | Operator other than CPL_EQUAL_TO or CPL_NOT_EQUAL_TO was specified.

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` and `CPL_NOT_EQUAL_TO`. If the table has no rows, no error is set, and 0 is returned. See also the function `cpl_table_or_selected_double_complex()`.

References CPL_ERROR_ILLEGAL_INPUT, cpl_table_get_nrow(), cpl_table_unselect_all(), cpl_table_unselect_row(), and CPL_TYPE_DOUBLE_COMPLEX.

## cpl_table_and_selected_float()

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

References cpl_table_get_nrow(), cpl_table_unselect_all(), cpl_table_unselect_row(), and CPL_TYPE_FLOAT.

## cpl_table_and_selected_float_complex()

cpl_size cpl_table_and_selected_float_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_table_select_operator | operator,
|  | float complex | value )

Select from selected table rows, by comparing float complex column values with a complex 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_COMPLEX.
  CPL_ERROR_ILLEGAL_INPUT | Operator other than CPL_EQUAL_TO or CPL_NOT_EQUAL_TO was specified.

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` and `CPL_NOT_EQUAL_TO`. If the table has no rows, no error is set, and 0 is returned. See also the function `cpl_table_or_selected_float_complex()`.

References CPL_ERROR_ILLEGAL_INPUT, cpl_table_get_nrow(), cpl_table_unselect_all(), cpl_table_unselect_row(), and CPL_TYPE_FLOAT_COMPLEX.

## cpl_table_and_selected_int()

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

References cpl_table_get_nrow(), cpl_table_unselect_all(), cpl_table_unselect_row(), and CPL_TYPE_INT.

## cpl_table_and_selected_invalid()

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

References cpl_table_unselect_all(), cpl_table_unselect_row(), CPL_TYPE_POINTER, and CPL_TYPE_STRING.

## cpl_table_and_selected_long()

cpl_size cpl_table_and_selected_long | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_table_select_operator | operator,
|  | long | value )

Select from selected table rows, by comparing long 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_LONG.

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

References cpl_table_get_nrow(), cpl_table_unselect_all(), cpl_table_unselect_row(), and CPL_TYPE_LONG.

## cpl_table_and_selected_long_long()

cpl_size cpl_table_and_selected_long_long | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_table_select_operator | operator,
|  | long long | value )

Select from selected table rows, by comparing long long 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_LONG_LONG.

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

References cpl_table_get_nrow(), cpl_table_unselect_all(), cpl_table_unselect_row(), and CPL_TYPE_LONG_LONG.

## cpl_table_and_selected_string()

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

References CPL_ERROR_ILLEGAL_INPUT, cpl_table_get_nrow(), cpl_table_unselect_all(), cpl_table_unselect_row(), and CPL_TYPE_STRING.

## cpl_table_and_selected_window()

cpl_size cpl_table_and_selected_window | ( | cpl_table * | table,
|  | cpl_size | start,
|  | cpl_size | 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()`.

References cpl_calloc(), CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_free().

## cpl_table_arg_column()

cpl_error_code cpl_table_arg_column | ( | cpl_table * | table,
|  | const char * | name )

Compute the phase angle value of table column elements.

Parameters

  table | Pointer to table.
  name | Column name.

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 neither numerical nor complex.

Each column element is replaced by its phase angle value. The phase angle will be in the range of [-pi,pi]. Invalid elements are not modified by this operation. If the column is complex, its type will be turned to real (CPL_TYPE_FLOAT_COMPLEX will be changed into CPL_TYPE_FLOAT, and CPL_TYPE_DOUBLE_COMPLEX will be changed into CPL_TYPE_DOUBLE), and any pointer retrieved by calling `cpl_table_get_data_float_complex()`, `cpl_table_get_data_double_complex()`, etc., should be discarded.

References CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, cpl_table_get_column_type(), cpl_table_get_data_double(), cpl_table_get_data_float(), cpl_table_get_nrow(), CPL_TYPE_COMPLEX, CPL_TYPE_DOUBLE, and CPL_TYPE_FLOAT.

## cpl_table_cast_column()

cpl_error_code cpl_table_cast_column | ( | cpl_table * | table,
|  | const char * | from_name,
|  | const char * | to_name,
|  | cpl_type | type )

Cast a numeric or complex column to a new numeric or complex 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 | Any of table or from_name is a NULL pointer.
  CPL_ERROR_ILLEGAL_OUTPUT | A column with the specified to_name already exists in table. Note however that to_name equal to from_name is legal (in-place cast).
  CPL_ERROR_DATA_NOT_FOUND | A column with the specified from_name is not found in table.
  CPL_ERROR_INVALID_TYPE | The specified column is neither numerical nor complex.
  CPL_ERROR_ILLEGAL_INPUT | The specified type is neither numerical nor complex.

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()`. Note that a column of arrays is always cast to another column of arrays of the specified type, unless it has depth 1. Consistently, a column of numbers can be cast to a column of arrays of depth 1. Here is a complete summary of how any (legal) type specification would be interpreted, depending on the type of the input column:

from_name type = CPL_TYPE_XXX
specified type = CPL_TYPE_XXX
to_name type = CPL_TYPE_XXX
from_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER
specified type = CPL_TYPE_XXX | CPL_TYPE_POINTER
to_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER
from_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER (depth > 1)
specified type = CPL_TYPE_XXX
to_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER
from_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER (depth = 1)
specified type = CPL_TYPE_XXX
to_name type = CPL_TYPE_XXX
from_name type = CPL_TYPE_XXX
specified type = CPL_TYPE_XXX | CPL_TYPE_POINTER
to_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER (depth = 1)
from_name type = CPL_TYPE_XXX
specified type = CPL_TYPE_POINTER
to_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER (depth = 1)
from_name type = CPL_TYPE_XXX
specified type = CPL_TYPE_YYY
to_name type = CPL_TYPE_YYY
from_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER
specified type = CPL_TYPE_YYY | CPL_TYPE_POINTER
to_name type = CPL_TYPE_YYY | CPL_TYPE_POINTER
from_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER (depth > 1)
specified type = CPL_TYPE_YYY
to_name type = CPL_TYPE_YYY | CPL_TYPE_POINTER
from_name type = CPL_TYPE_XXX | CPL_TYPE_POINTER (depth = 1)
specified type = CPL_TYPE_YYY
to_name type = CPL_TYPE_YYY
from_name type = CPL_TYPE_XXX
specified type = CPL_TYPE_YYY | CPL_TYPE_POINTER
to_name type = CPL_TYPE_YYY | CPL_TYPE_POINTER (depth = 1)
CPL_TYPE_POINTER
@ CPL_TYPE_POINTER
Definition cpl_type.h:140

Note
  If to_name is a NULL pointer, or it is equal to from_name, the cast is done in-place. The pointers to data will change, therefore pointers previously retrieved by `cpl_table_get_data_xxx()`, should be discarded.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, cpl_table_erase_column(), cpl_table_get_column_depth(), cpl_table_get_column_type(), CPL_TYPE_DOUBLE, CPL_TYPE_DOUBLE_COMPLEX, CPL_TYPE_FLOAT, CPL_TYPE_FLOAT_COMPLEX, CPL_TYPE_INT, CPL_TYPE_LONG, CPL_TYPE_LONG_LONG, and CPL_TYPE_POINTER.

Referenced by cpl_plot_column(), and cpl_plot_columns().

## cpl_table_compare_structure()

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, the same types, and the same units. The order of the columns is not relevant.

References cpl_array_delete(), cpl_array_get_string(), cpl_table_get_column_depth(), cpl_table_get_column_names(), cpl_table_get_column_type(), cpl_table_get_column_unit(), cpl_table_get_ncol(), and cpl_table_has_column().

Referenced by cpl_table_insert().

## cpl_table_conjugate_column()

cpl_error_code cpl_table_conjugate_column | ( | cpl_table * | table,
|  | const char * | name )

Compute the complex conjugate of column values.

Parameters

  table | Pointer to table.
  name | Column name.

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 neither numerical nor complex, or it is integer, or it is an array column.
  CPL_ERROR_ILLEGAL_INPUT | The input base is not positive.

Each column element is replaced by its complex conjugate. 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.

References CPL_ERROR_NONE.

## cpl_table_copy_data_double()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_copy_data_double_complex()

cpl_error_code cpl_table_copy_data_double_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | const double complex * | data )

Copy existing data to a table double complex 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_COMPLEX.

See the description of `cpl_table_copy_data_int()` for details.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_copy_data_float()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_copy_data_float_complex()

cpl_error_code cpl_table_copy_data_float_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | const float complex * | data )

Copy existing data to a table float complex 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_COMPLEX.

See the description of `cpl_table_copy_data_int()` for details.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_copy_data_int()

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_copy_data_long()

cpl_error_code cpl_table_copy_data_long | ( | cpl_table * | table,
|  | const char * | name,
|  | const long * | data )

Copy existing data to a table long 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_LONG.

See the description of `cpl_table_copy_data_int()` for details.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_copy_data_long_long()

cpl_error_code cpl_table_copy_data_long_long | ( | cpl_table * | table,
|  | const char * | name,
|  | const long long * | data )

Copy existing data to a table long long 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_LONG_LONG.

See the description of `cpl_table_copy_data_int()` for details.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_copy_data_string()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_copy_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.

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, units) of a given model table. All columns are physically created in the new table, and they are initialised to contain just invalid elements.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_table_get_ncol(), cpl_table_new_column(), cpl_table_new_column_array(), cpl_table_set_column_format(), cpl_table_set_column_unit(), and CPL_TYPE_POINTER.

Referenced by cpl_table_extract_selected().

## cpl_table_count_invalid()

cpl_size 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.

Referenced by cpl_plot_column().

## cpl_table_count_selected()

cpl_size 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.

References CPL_ERROR_NULL_INPUT.

## cpl_table_delete()

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.

References cpl_free(), and cpl_table_get_ncol().

Referenced by cpl_plot_column(), cpl_plot_columns(), cpl_ppm_match_points(), and cpl_table_extract().

## cpl_table_divide_columns()

cpl_error_code cpl_table_divide_columns | ( | cpl_table * | table,
|  | const char * | to_name,
|  | const char * | from_name )

Divide two numeric or complex 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 neither numerical nor complex, or it is an array column.

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.

References CPL_ERROR_NONE.

## cpl_table_divide_scalar()

cpl_error_code cpl_table_divide_scalar | ( | cpl_table * | table,
|  | const char * | name,
|  | double | value )

Divide a numerical or complex 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 neither numerical nor complex, or it is an array column.
  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.

References CPL_ERROR_NONE.

## cpl_table_divide_scalar_complex()

cpl_error_code cpl_table_divide_scalar_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | double complex | value )

Divide a numerical or complex column by a complex 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 neither numerical nor complex, or it is an array column.
  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.

References CPL_ERROR_NONE.

## cpl_table_dump()

void cpl_table_dump | ( | const cpl_table * | table,
|  | cpl_size | start,
|  | cpl_size | 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 "-" as wide as the field occupied by the column to which they belong. Array elements are not resolved, and are represented by a sequence of "+" 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()`.

References cpl_calloc(), cpl_free(), cpl_malloc(), CPL_SIZE_FORMAT, cpl_sprintf(), cpl_table_get_ncol(), CPL_TYPE_DOUBLE, CPL_TYPE_DOUBLE_COMPLEX, CPL_TYPE_FLOAT, CPL_TYPE_FLOAT_COMPLEX, CPL_TYPE_INT, CPL_TYPE_LONG, CPL_TYPE_LONG_LONG, and CPL_TYPE_STRING.

## cpl_table_dump_structure()

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

References CPL_SIZE_FORMAT, cpl_table_get_ncol(), CPL_TYPE_DOUBLE, CPL_TYPE_DOUBLE_COMPLEX, CPL_TYPE_FLOAT, CPL_TYPE_FLOAT_COMPLEX, CPL_TYPE_INT, CPL_TYPE_LONG, CPL_TYPE_LONG_LONG, and CPL_TYPE_STRING.

## cpl_table_duplicate()

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.

References cpl_malloc(), cpl_table_get_ncol(), cpl_table_get_nrow(), and cpl_table_new().

Referenced by cpl_table_extract_selected().

## cpl_table_duplicate_column()

cpl_error_code cpl_table_duplicate_column | ( | cpl_table * | to_table,
|  | const char * | to_name,
|  | const 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.

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plot_column(), and cpl_plot_columns().

## cpl_table_erase_column()

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, also the selection flags are lost.

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plot_columns(), cpl_table_cast_column(), cpl_table_erase_invalid(), and cpl_table_erase_invalid_rows().

## cpl_table_erase_invalid()

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 set back to "all selected" 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()`, etc., should be discarded.

The function is similar to the function cpl_table_erase_invalid_rows(), except for the criteria to remove rows containing invalid elements after all invalid columns have been removed. While cpl_table_erase_invalid_rows() requires all elements to be invalid in order to remove a row from the table, this function requires only one (or more) elements to be invalid.

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

See also
  cpl_table_erase_invalid_rows()

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_table_erase_column(), cpl_table_erase_window(), cpl_table_get_ncol(), cpl_table_get_nrow(), and cpl_table_select_all().

Referenced by cpl_plot_column().

## cpl_table_erase_invalid_rows()

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, i.e. a column or a row is deleted only if all of its elements are invalid. The selection flags are set back to "all selected" 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.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_table_erase_column(), cpl_table_erase_window(), cpl_table_get_ncol(), cpl_table_get_nrow(), and cpl_table_select_all().

## cpl_table_erase_selected()

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 set back to "all selected".

References CPL_ERROR_NULL_INPUT, cpl_table_get_ncol(), cpl_table_get_nrow(), cpl_table_select_all(), and cpl_table_set_size().

## cpl_table_erase_window()

cpl_error_code cpl_table_erase_window | ( | cpl_table * | table,
|  | cpl_size | start,
|  | cpl_size | 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 set back to "all selected". 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.

References CPL_ERROR_NULL_INPUT, cpl_table_get_ncol(), and cpl_table_select_all().

Referenced by cpl_table_erase_invalid(), and cpl_table_erase_invalid_rows().

## cpl_table_exponential_column()

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 neither numerical nor complex, or it is an array column.
  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.

References CPL_ERROR_NONE.

## cpl_table_extract()

cpl_table * cpl_table_extract | ( | const cpl_table * | table,
|  | cpl_size | start,
|  | cpl_size | 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.

References CPL_ERROR_NULL_INPUT, cpl_table_delete(), cpl_table_get_ncol(), cpl_table_get_nrow(), and cpl_table_new().

## cpl_table_extract_selected()

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.

References CPL_ERROR_NULL_INPUT, cpl_table_copy_structure(), cpl_table_duplicate(), cpl_table_new(), CPL_TYPE_DOUBLE, CPL_TYPE_DOUBLE_COMPLEX, CPL_TYPE_FLOAT, CPL_TYPE_FLOAT_COMPLEX, CPL_TYPE_INT, CPL_TYPE_LONG_LONG, and CPL_TYPE_STRING.

## cpl_table_fill_column_window()

cpl_error_code cpl_table_fill_column_window | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | 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, or is of type array.

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.

References CPL_ERROR_NONE.

## cpl_table_fill_column_window_array()

cpl_error_code cpl_table_fill_column_window_array | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | count,
|  | const cpl_array * | array )

Write an array to an array column segment.

Parameters

  table | Pointer to table.
  name | Name of table column to access.
  start | Position where to begin to write the array.
  count | Number of arrays to write.
  array | Array 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 does not match the type of the input array, or it is not made of arrays.
  CPL_ERROR_INCOMPATIBLE_INPUT | The size of the input array is different from the depth of the specified column.

Write the same array to a segment of an array column. If the input array is not a `NULL` pointer, it is duplicated for each accessed column element. If the input array 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.

References CPL_ERROR_NONE.

## cpl_table_fill_column_window_complex()

cpl_error_code cpl_table_fill_column_window_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | count,
|  | double complex | value )

Write a value to a complex 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 complex, or is of type array.

Write the same value to a complex 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.

References CPL_ERROR_NONE.

## cpl_table_fill_column_window_double()

cpl_error_code cpl_table_fill_column_window_double | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | 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.

References CPL_ERROR_NONE.

Referenced by cpl_ppm_match_points().

## cpl_table_fill_column_window_double_complex()

cpl_error_code cpl_table_fill_column_window_double_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | count,
|  | double complex | value )

Write a value to a double complex 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_COMPLEX.

Write the same value to a double complex 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.

References CPL_ERROR_NONE.

## cpl_table_fill_column_window_float()

cpl_error_code cpl_table_fill_column_window_float | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | 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.

References CPL_ERROR_NONE.

## cpl_table_fill_column_window_float_complex()

cpl_error_code cpl_table_fill_column_window_float_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | count,
|  | float complex | value )

Write a value to a float complex 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_COMPLEX.

Write the same value to a float complex 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.

References CPL_ERROR_NONE.

## cpl_table_fill_column_window_int()

cpl_error_code cpl_table_fill_column_window_int | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | 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()`.

References CPL_ERROR_NONE.

## cpl_table_fill_column_window_long()

cpl_error_code cpl_table_fill_column_window_long | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | count,
|  | long | value )

Write a value to an long 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_LONG.

Write the same value to an long 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()`.

References CPL_ERROR_NONE.

## cpl_table_fill_column_window_long_long()

cpl_error_code cpl_table_fill_column_window_long_long | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | count,
|  | long long | value )

Write a value to an long long 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_LONG_LONG.

Write the same value to an long long 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()`.

References CPL_ERROR_NONE.

## cpl_table_fill_column_window_string()

cpl_error_code cpl_table_fill_column_window_string | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | count,
|  | const 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.

References CPL_ERROR_NONE.

## cpl_table_fill_invalid_double()

cpl_error_code cpl_table_fill_invalid_double | ( | cpl_table * | table,
|  | const char * | name,
|  | double | code )

Write a numerical value to invalid double column elements.

Parameters

  table | Pointer to table containing the column.
  name | Column name.
  code | Value 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, or of type CPL_TYPE_DOUBLE | CPL_TYPE_POINTER.

See also
  cpl_table_fill_invalid_int()

Note
  Assigning a value to an invalid numerical element will not make it valid, but assigning a value to an element consisting of an array of numbers will make the array element valid.

References CPL_ERROR_NONE.

## cpl_table_fill_invalid_double_complex()

cpl_error_code cpl_table_fill_invalid_double_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | double complex | code )

Write a numerical value to invalid double complex column elements.

Parameters

  table | Pointer to table containing the column.
  name | Column name.
  code | Value 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_COMPLEX, or of type CPL_TYPE_DOUBLE_COMPLEX | CPL_TYPE_POINTER.

See also
  cpl_table_fill_invalid_int()

Note
  Assigning a value to an invalid numerical element will not make it valid, but assigning a value to an element consisting of an array of numbers will make the array element valid.

References CPL_ERROR_NONE.

## cpl_table_fill_invalid_float()

cpl_error_code cpl_table_fill_invalid_float | ( | cpl_table * | table,
|  | const char * | name,
|  | float | code )

Write a numerical value to invalid float column elements.

Parameters

  table | Pointer to table containing the column.
  name | Column name.
  code | Value 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, or of type CPL_TYPE_FLOAT | CPL_TYPE_POINTER.

See also
  cpl_table_fill_invalid_int()

Note
  Assigning a value to an invalid numerical element will not make it valid, but assigning a value to an element consisting of an array of numbers will make the array element valid.

References CPL_ERROR_NONE.

## cpl_table_fill_invalid_float_complex()

cpl_error_code cpl_table_fill_invalid_float_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | float complex | code )

Write a numerical value to invalid float complex column elements.

Parameters

  table | Pointer to table containing the column.
  name | Column name.
  code | Value 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_COMPLEX, or of type CPL_TYPE_FLOAT_COMPLEX | CPL_TYPE_POINTER.

See also
  cpl_table_fill_invalid_int()

Note
  Assigning a value to an invalid numerical element will not make it valid, but assigning a value to an element consisting of an array of numbers will make the array element valid.

References CPL_ERROR_NONE.

## cpl_table_fill_invalid_int()

cpl_error_code cpl_table_fill_invalid_int | ( | cpl_table * | table,
|  | const char * | name,
|  | int | code )

Write a numerical value to invalid integer column elements.

Parameters

  table | Pointer to table containing the column.
  name | Column name.
  code | Value 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, or of type CPL_TYPE_INT | CPL_TYPE_POINTER.

In general, a numeric column element that is flagged as invalid is undefined and should not be read. It is however sometimes convenient to read such values, f.ex. via calls to `cpl_table_get_data_int()` and memcpy(). In order to avoid that such usage causes uninitialized memory to be read, the invalid elements may be set to a value specified by a call to this function. Note that only existing invalid elements will be filled 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 value to a given invalid column element: therefore the value should be applied just before it is actually needed. An invalid numerical column element remains invalid after this call, and the usual method of checking whether the element is invalid or not should still be used. This function can be applied also to columns of arrays of integers. In this case the call will cause the array element to be flagged as valid.

Note
  Assigning a value to an invalid numerical element will not make it valid, but assigning a value to an element consisting of an array of numbers will make the array element valid.

References CPL_ERROR_NONE.

## cpl_table_fill_invalid_long()

cpl_error_code cpl_table_fill_invalid_long | ( | cpl_table * | table,
|  | const char * | name,
|  | long | code )

Write a numerical value to invalid long column elements.

Parameters

  table | Pointer to table containing the column.
  name | Column name.
  code | Value 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_LONG, or of type CPL_TYPE_LONG | CPL_TYPE_POINTER.

See also
  cpl_table_fill_invalid_int()

Note
  Assigning a value to an invalid numerical element will not make it valid, but assigning a value to an element consisting of an array of numbers will make the array element valid.

References CPL_ERROR_NONE.

## cpl_table_fill_invalid_long_long()

cpl_error_code cpl_table_fill_invalid_long_long | ( | cpl_table * | table,
|  | const char * | name,
|  | long long | code )

Write a numerical value to invalid long long column elements.

Parameters

  table | Pointer to table containing the column.
  name | Column name.
  code | Value 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_LONG_LONG, or of type CPL_TYPE_LONG_LONG | CPL_TYPE_POINTER.

See also
  cpl_table_fill_invalid_int()

Note
  Assigning a value to an invalid numerical element will not make it valid, but assigning a value to an element consisting of an array of numbers will make the array element valid.

References CPL_ERROR_NONE.

## cpl_table_get()

double cpl_table_get | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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, or is a column of arrays.

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`.

References CPL_ERROR_INVALID_TYPE, CPL_SIZE_FORMAT, CPL_TYPE_COMPLEX, cpl_type_get_name(), CPL_TYPE_POINTER, and CPL_TYPE_STRING.

## cpl_table_get_array()

const cpl_array * cpl_table_get_array | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row )

Read an array from an array column.

Parameters

  table | Pointer to table.
  name | Name of table column to access.
  row | Position of element to be read.

Returns
  Pointer to array. 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 array.

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

Note
  The returned array 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_array()` will turn it into garbage. Therefore, if a real copy of an array column element is required, this function should be called as an argument of the function `cpl_array_duplicate()`.

References CPL_TYPE_POINTER.

## cpl_table_get_column_depth()

cpl_size cpl_table_get_column_depth | ( | const cpl_table * | table,
|  | const char * | name )

Get the depth of a table column.

Parameters

  table | Pointer to table.
  name | Column name.

Returns
  Column depth, or -1 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 depth of a column. Columns of type array always have positive depth, while columns listing numbers or character strings have depth 0.

Referenced by cpl_table_cast_column(), and cpl_table_compare_structure().

## cpl_table_get_column_dimension()

cpl_size cpl_table_get_column_dimension | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | indx )

Get size of one dimension of a table column of arrays.

Parameters

  table | Pointer to table.
  name | Column name.
  indx | Indicate dimension to query (0 = x, 1 = y, 2 = z, etc.).

Returns
  Size of queried dimension of the column, or zero 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.
  CPL_ERROR_UNSUPPORTED_MODE | The specified column is not of type array.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The specified indx array is not compatible with the column dimensions.
  CPL_ERROR_INCOMPATIBLE_INPUT | The specified dimensions are incompatible with the total number of elements in the column arrays.

Get the size of one dimension of a column. If a column is not an array column, or if it has no dimensions, 1 is returned.

## cpl_table_get_column_dimensions()

cpl_size cpl_table_get_column_dimensions | ( | const cpl_table * | table,
|  | const char * | name )

Get the number of dimensions of a table column of arrays.

Parameters

  table | Pointer to table.
  name | Column name.

Returns
  Column number of dimensions, or 0 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 number of dimensions of a column. If a column is not an array column, or if it has no dimensions, 1 is returned.

## cpl_table_get_column_format()

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

## cpl_table_get_column_max()

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

References cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_table_get_column_maxpos()

cpl_error_code cpl_table_get_column_maxpos | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size * | 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.

References CPL_ERROR_NONE.

## cpl_table_get_column_mean()

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.

References cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_table_get_column_mean_complex()

double complex cpl_table_get_column_mean_complex | ( | const cpl_table * | table,
|  | const char * | name )

Compute the mean value of a numerical or complex 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 neither numerical nor complex.

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

References cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_table_get_column_median()

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

References cpl_errorstate_get(), and cpl_errorstate_is_equal().

Referenced by cpl_ppm_match_points().

## cpl_table_get_column_min()

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

References cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_table_get_column_minpos()

cpl_error_code cpl_table_get_column_minpos | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size * | 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()`.

References CPL_ERROR_NONE.

## cpl_table_get_column_name()

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

Deprecated
  This function is deprecated, because its usage could create serious problems in case it is attempted to get names from different tables simultaneously. For instance, a programmer may call cpl_table_get_column_name() in a loop, and in the same loop call a CPL function that calls as well the same function. The behaviour in this case would be unpredictable. The function cpl_table_get_column_names() should be used instead.

References cpl_table_get_ncol().

## cpl_table_get_column_names()

cpl_array * cpl_table_get_column_names | ( | const cpl_table * | table | ) |

Get table columns names.

Parameters

  table | Pointer to table.

Returns
  Array of table columns names.

The returned CPL array of strings should be finally destroyed using cpl_array_delete().

References cpl_array_new(), cpl_array_set_string(), CPL_ERROR_NULL_INPUT, and CPL_TYPE_STRING.

Referenced by cpl_table_compare_structure().

## cpl_table_get_column_stdev()

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.

References cpl_errorstate_get(), and cpl_errorstate_is_equal().

Referenced by cpl_ppm_match_points().

## cpl_table_get_column_type()

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.

References CPL_TYPE_INVALID.

Referenced by cpl_plot_column(), cpl_plot_columns(), cpl_table_abs_column(), cpl_table_arg_column(), cpl_table_cast_column(), cpl_table_compare_structure(), cpl_table_imag_column(), cpl_table_real_column(), and cpl_table_unwrap().

## cpl_table_get_column_unit()

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, otherwise a NULL pointer is returned. 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()`.

Referenced by cpl_table_compare_structure().

## cpl_table_get_complex()

double complex cpl_table_get_complex | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | int * | null )

Read a value from a complex 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 complex, or is a column of arrays.

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`.

References CPL_ERROR_INVALID_TYPE, CPL_SIZE_FORMAT, CPL_TYPE_COMPLEX, cpl_type_get_name(), and CPL_TYPE_POINTER.

## cpl_table_get_data_array()

cpl_array ** cpl_table_get_data_array | ( | cpl_table * | table,
|  | const char * | name )

Get a pointer to array 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 array.

A table column of type array includes an array of values of type cpl_array*. 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.

References CPL_TYPE_POINTER.

## cpl_table_get_data_array_const()

const cpl_array ** cpl_table_get_data_array_const | ( | const cpl_table * | table,
|  | const char * | name )

Get a pointer to array 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 array.

A table column of type array includes an array of values of type cpl_array*. This function returns a pointer to this array.

References CPL_TYPE_POINTER.

## cpl_table_get_data_double()

double * cpl_table_get_data_double | ( | cpl_table * | table,
|  | const char * | name )

Get a pointer to double column data.

Parameters

  table | Pointer to table.
  name | Column name.

Returns
  Pointer to 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.

References CPL_TYPE_DOUBLE.

Referenced by cpl_plot_column(), cpl_ppm_match_points(), cpl_table_arg_column(), and cpl_table_imag_column().

## cpl_table_get_data_double_complex()

double complex * cpl_table_get_data_double_complex | ( | cpl_table * | table,
|  | const char * | name )

Get a pointer to double complex 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_COMPLEX.

A cpl_table column of type `CPL_TYPE_DOUBLE_COMPLEX` includes an array of values of type double complex. 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_complex()` 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_complex()` 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.

References CPL_TYPE_DOUBLE_COMPLEX.

## cpl_table_get_data_double_complex_const()

const double complex * cpl_table_get_data_double_complex_const | ( | const cpl_table * | table,
|  | const char * | name )

Get a pointer to constant double complex column data.

Parameters

  table | Pointer to constant table.
  name | Column name.

Returns
  Pointer to constant 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_COMPLEX.

A cpl_table column of type `CPL_TYPE_DOUBLE_COMPLEX` includes an array of values of type double complex. 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_complex()` 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_complex()` for further details.

References CPL_TYPE_DOUBLE_COMPLEX.

## cpl_table_get_data_double_const()

const double * cpl_table_get_data_double_const | ( | const cpl_table * | table,
|  | const char * | name )

Get a pointer to constant double column data.

Parameters

  table | Pointer to constant table.
  name | Column name.

Returns
  Pointer to constant 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.

References CPL_TYPE_DOUBLE.

Referenced by cpl_plot_column(), and cpl_plot_columns().

## cpl_table_get_data_float()

float * cpl_table_get_data_float | ( | cpl_table * | table,
|  | const char * | name )

Get a pointer to float column data.

Parameters

  table | Pointer to table.
  name | Column name.

Returns
  Pointer to 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.

References CPL_TYPE_FLOAT.

Referenced by cpl_table_arg_column(), and cpl_table_imag_column().

## cpl_table_get_data_float_complex()

float complex * cpl_table_get_data_float_complex | ( | cpl_table * | table,
|  | const char * | name )

Get a pointer to float complex 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_COMPLEX.

A cpl_table column of type `CPL_TYPE_FLOAT_COMPLEX` includes an array of values of type float complex. 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_complex()` 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_complex()` 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.

References CPL_TYPE_FLOAT_COMPLEX.

## cpl_table_get_data_float_complex_const()

const float complex * cpl_table_get_data_float_complex_const | ( | const cpl_table * | table,
|  | const char * | name )

Get a pointer to constant float complex column data.

Parameters

  table | Pointer to constant table.
  name | Column name.

Returns
  Pointer to constant 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_COMPLEX.

A cpl_table column of type `CPL_TYPE_FLOAT_COMPLEX` includes an array of values of type float complex. 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_complex()` 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_complex()` for further details.

References CPL_TYPE_FLOAT_COMPLEX.

## cpl_table_get_data_float_const()

const float * cpl_table_get_data_float_const | ( | const cpl_table * | table,
|  | const char * | name )

Get a pointer to constant float column data.

Parameters

  table | Pointer to constant table.
  name | Column name.

Returns
  Pointer to constant 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.

References CPL_TYPE_FLOAT.

## cpl_table_get_data_int()

int * cpl_table_get_data_int | ( | cpl_table * | table,
|  | const char * | name )

Get a pointer to integer column data.

Parameters

  table | Pointer to table.
  name | Column name.

Returns
  Pointer to 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.

References CPL_TYPE_INT.

## cpl_table_get_data_int_const()

const int * cpl_table_get_data_int_const | ( | const cpl_table * | table,
|  | const char * | name )

Get a pointer to constant integer column data.

Parameters

  table | Pointer to constant table.
  name | Column name.

Returns
  Pointer to constant 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.

References CPL_TYPE_INT.

## cpl_table_get_data_long()

long * cpl_table_get_data_long | ( | cpl_table * | table,
|  | const char * | name )

Get a pointer to long 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_LONG.

A cpl_table column of type `CPL_TYPE_LONG` includes an array of values of type long. 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_long()` 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_long()` 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.

References CPL_TYPE_LONG.

## cpl_table_get_data_long_const()

const long * cpl_table_get_data_long_const | ( | const cpl_table * | table,
|  | const char * | name )

Get a pointer to constant long column data.

Parameters

  table | Pointer to constant table.
  name | Column name.

Returns
  Pointer to constant 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_LONG.

A cpl_table column of type `CPL_TYPE_LONG` includes an array of values of type long. 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_long()` 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_long()` for further details.

References CPL_TYPE_LONG.

## cpl_table_get_data_long_long()

long long * cpl_table_get_data_long_long | ( | cpl_table * | table,
|  | const char * | name )

Get a pointer to long long 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_LONG_LONG.

A cpl_table column of type `CPL_TYPE_LONG_LONG` includes an array of values of type long long. 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_long_long()` 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_long_long()` 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.

References CPL_TYPE_LONG_LONG.

## cpl_table_get_data_long_long_const()

const long long * cpl_table_get_data_long_long_const | ( | const cpl_table * | table,
|  | const char * | name )

Get a pointer to constant long long column data.

Parameters

  table | Pointer to constant table.
  name | Column name.

Returns
  Pointer to constant 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_LONG_LONG.

A cpl_table column of type `CPL_TYPE_LONG_LONG` includes an array of values of type long long. 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_long_long()` 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_long_long()` for further details.

References CPL_TYPE_LONG_LONG.

## cpl_table_get_data_string()

char ** cpl_table_get_data_string | ( | cpl_table * | table,
|  | const char * | name )

Get a pointer to string column data.

Parameters

  table | Pointer to table.
  name | Column name.

Returns
  Pointer to 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.

References CPL_TYPE_STRING.

## cpl_table_get_data_string_const()

const char ** cpl_table_get_data_string_const | ( | const cpl_table * | table,
|  | const char * | name )

Get a pointer to constant string column data.

Parameters

  table | Pointer to constant table.
  name | Column name.

Returns
  Pointer to constant 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.

References CPL_TYPE_STRING.

## cpl_table_get_double()

double cpl_table_get_double | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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().

References CPL_TYPE_DOUBLE.

## cpl_table_get_double_complex()

double complex cpl_table_get_double_complex | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | int * | null )

Read a value from a double complex 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 complex 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_COMPLEX.

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

References CPL_TYPE_DOUBLE_COMPLEX.

## cpl_table_get_float()

float cpl_table_get_float | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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().

References CPL_TYPE_FLOAT.

## cpl_table_get_float_complex()

float complex cpl_table_get_float_complex | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | int * | null )

Read a value from a float complex 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 complex 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_COMPLEX.

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

References CPL_TYPE_FLOAT_COMPLEX.

## cpl_table_get_int()

int cpl_table_get_int | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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()`.

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_NULL_INPUT, CPL_ERROR_TYPE_MISMATCH, CPL_SIZE_FORMAT, cpl_type_get_name(), and CPL_TYPE_INT.

## cpl_table_get_long()

long cpl_table_get_long | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | int * | null )

Read a value from a long 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
  Long 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_LONG.

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

References CPL_TYPE_LONG.

## cpl_table_get_long_long()

long long cpl_table_get_long_long | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | int * | null )

Read a value from a long long 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
  Long long 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_LONG_LONG.

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

References CPL_TYPE_LONG_LONG.

## cpl_table_get_ncol()

cpl_size 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.

References CPL_ERROR_NULL_INPUT, and cpl_error_set.

Referenced by cpl_table_compare_structure(), cpl_table_copy_structure(), cpl_table_delete(), cpl_table_dump(), cpl_table_dump_structure(), cpl_table_duplicate(), cpl_table_erase_invalid(), cpl_table_erase_invalid_rows(), cpl_table_erase_selected(), cpl_table_erase_window(), cpl_table_extract(), cpl_table_get_column_name(), cpl_table_insert(), cpl_table_insert_window(), and cpl_table_set_size().

## cpl_table_get_nrow()

cpl_size 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.

References CPL_ERROR_NULL_INPUT, and cpl_error_set.

Referenced by cpl_plot_column(), cpl_plot_columns(), cpl_ppm_match_points(), cpl_table_and_selected(), cpl_table_and_selected_double(), cpl_table_and_selected_double_complex(), cpl_table_and_selected_float(), cpl_table_and_selected_float_complex(), cpl_table_and_selected_int(), cpl_table_and_selected_long(), cpl_table_and_selected_long_long(), cpl_table_and_selected_string(), cpl_table_arg_column(), cpl_table_duplicate(), cpl_table_erase_invalid(), cpl_table_erase_invalid_rows(), cpl_table_erase_selected(), cpl_table_extract(), and cpl_table_imag_column().

## cpl_table_get_string()

const char * cpl_table_get_string | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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()`.

References CPL_TYPE_STRING.

## cpl_table_has_column()

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.

References CPL_ERROR_NULL_INPUT, and cpl_error_set.

Referenced by cpl_plot_column(), cpl_plot_columns(), and cpl_table_compare_structure().

## cpl_table_has_invalid()

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. In case of columns of arrays, invalid values within an array are not considered: an invalid element here means that an array element is not allocated, i.e., it is a `NULL` pointer. In order to detect invalid elements within an array element, this element must be extracted using the function `cpl_table_get_array()`, and then use the function `cpl_array_has_invalid()`.

References cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_table_has_valid()

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. In case of columns of arrays, invalid values within an array are not considered: an invalid element here means that an array element is not allocated, i.e., it is a `NULL` pointer. In order to detect valid elements within an array element, this element must be extracted using the function `cpl_table_get_array()`, and then use the function `cpl_array_has_valid()`.

References cpl_errorstate_get(), and cpl_errorstate_is_equal().

Referenced by cpl_ppm_match_points().

## cpl_table_imag_column()

cpl_error_code cpl_table_imag_column | ( | cpl_table * | table,
|  | const char * | name )

Compute the imaginary part value of table column elements.

Parameters

  table | Pointer to table.
  name | Column name.

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 neither numerical nor complex.

Each column element is replaced by its imaginary party value only. Invalid elements are not modified by this operation. If the column is complex, its type will be turned to real (CPL_TYPE_FLOAT_COMPLEX will be changed into CPL_TYPE_FLOAT, and CPL_TYPE_DOUBLE_COMPLEX will be changed into CPL_TYPE_DOUBLE), and any pointer retrieved by calling `cpl_table_get_data_float_complex()`, `cpl_table_get_data_double_complex()`, etc., should be discarded.

References CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, cpl_table_get_column_type(), cpl_table_get_data_double(), cpl_table_get_data_float(), cpl_table_get_nrow(), CPL_TYPE_COMPLEX, CPL_TYPE_DOUBLE, and CPL_TYPE_FLOAT.

## cpl_table_insert()

cpl_error_code cpl_table_insert | ( | cpl_table * | target_table,
|  | const cpl_table * | insert_table,
|  | cpl_size | 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 set back to "all selected". 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.

References CPL_ERROR_INCOMPATIBLE_INPUT, cpl_table_compare_structure(), cpl_table_get_ncol(), and cpl_table_select_all().

## cpl_table_insert_window()

cpl_error_code cpl_table_insert_window | ( | cpl_table * | table,
|  | cpl_size | start,
|  | cpl_size | 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 set back to "all selected".

References CPL_ERROR_NULL_INPUT, cpl_table_get_ncol(), and cpl_table_select_all().

## cpl_table_is_selected()

int cpl_table_is_selected | ( | const cpl_table * | table,
|  | cpl_size | 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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, and CPL_ERROR_NULL_INPUT.

## cpl_table_is_valid()

int cpl_table_is_valid | ( | const cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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.

References cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_table_load()

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, or, if it is a table, it has more than 9999 columns.
  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_table_load_window()

cpl_table * cpl_table_load_window | ( | const char * | filename,
|  | int | xtnum,
|  | int | check_nulls,
|  | const cpl_array * | selcol,
|  | cpl_size | firstrow,
|  | cpl_size | nrow )

Load part of 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.
  selcol | Array with the names of the columns to extract.
  firstrow | First table row to extract.
  nrow | Number of rows to extract.

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. Or the specified number of rows to extract is less than zero. Or the array of column names to extract contains empty fields.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | xtnum is greater than the number of FITS extensions in the FITS file, or is less than 1. Or firstrow is either less than zero, or greater than the number of rows in the table.
  CPL_ERROR_DATA_NOT_FOUND | The FITS table has no columns. Or selcol includes columns that are not found in table.
  CPL_ERROR_UNSPECIFIED | Generic error condition, that should be reported to the CPL Team.

The selected FITS file table extension is just read in the specified columns and rows intervals, and converted into the cpl_table conventions. If selcol is NULL, all columns are selected.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, and CPL_ERROR_ILLEGAL_INPUT.

## cpl_table_logarithm_column()

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 neither numerical nor complex, or it is an array column.
  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. In case of complex numbers, values very close to the origin may cause an overflow. The imaginary part of the result is chosen in the interval [-pi/ln(base),pi/ln(base)], so it should be kept in mind that doing the logarithm of exponential of a complex number will not always express the phase angle with the same number. For instance, the exponential in base 2 of (5.00, 5.00) is (-30.33, -10.19), and the logarithm in base 2 of the latter will be expressed as (5.00, -4.06).

References CPL_ERROR_NONE.

## cpl_table_move_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.

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.

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_multiply_columns()

cpl_error_code cpl_table_multiply_columns | ( | cpl_table * | table,
|  | const char * | to_name,
|  | const char * | from_name )

Multiply two numeric or complex 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 neither numerical nor complex, or it is an array column.

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.

References CPL_ERROR_NONE.

## cpl_table_multiply_scalar()

cpl_error_code cpl_table_multiply_scalar | ( | cpl_table * | table,
|  | const char * | name,
|  | double | value )

Multiply a numerical or complex 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 neither numerical nor complex, or it is an array column.

See the description of the function `cpl_table_add_scalar()`.

References CPL_ERROR_NONE.

## cpl_table_multiply_scalar_complex()

cpl_error_code cpl_table_multiply_scalar_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | double complex | value )

Multiply a numerical or complex column by a complex 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 neither numerical nor complex, or it is an array column.

See the description of the function `cpl_table_add_scalar_complex()`.

References CPL_ERROR_NONE.

## cpl_table_name_column()

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.

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_OUTPUT, and CPL_ERROR_NULL_INPUT.

## cpl_table_new()

cpl_table * cpl_table_new | ( | cpl_size | 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.

References cpl_calloc(), CPL_ERROR_ILLEGAL_INPUT, and cpl_error_set.

Referenced by cpl_plot_column(), cpl_plot_columns(), cpl_ppm_match_points(), cpl_table_duplicate(), cpl_table_extract(), and cpl_table_extract_selected().

## cpl_table_new_column()

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 | Type 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, excluding array types (for creating a column of arrays use the function `cpl_table_new_column_array()`, where the column depth must also be specified). 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.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_TYPE_DOUBLE, CPL_TYPE_DOUBLE_COMPLEX, CPL_TYPE_FLOAT, CPL_TYPE_FLOAT_COMPLEX, CPL_TYPE_INT, CPL_TYPE_LONG, CPL_TYPE_LONG_LONG, and CPL_TYPE_STRING.

Referenced by cpl_ppm_match_points(), and cpl_table_copy_structure().

## cpl_table_new_column_array()

cpl_error_code cpl_table_new_column_array | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_type | type,
|  | cpl_size | depth )

Create an empty column of arrays in a table.

Parameters

  table | Pointer to table.
  name | Name of the new column.
  type | Type of the new column.
  depth | Depth 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_INPUT | The specified depth is negative.
  CPL_ERROR_ILLEGAL_OUTPUT | A column with the same name already exists in table.

This function allocates memory for a new column of specified array type, (for creating a column of simple scalars or character strings use the function `cpl_table_new_column()` instead). It doesn't make any difference if a simple or an array type is specified, the corresponding array type will always be created (e.g., specifying a type `CPL_TYPE_INT` or a type `CPL_TYPE_INT` | `CPL_TYPE_POINTER` would always create a column of type `CPL_TYPE_INT` | `CPL_TYPE_POINTER`). 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.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and CPL_TYPE_LONG.

Referenced by cpl_table_copy_structure().

## cpl_table_not_selected()

cpl_size 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.

References CPL_ERROR_NULL_INPUT.

## cpl_table_or_selected()

cpl_size 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 | Invalid types for comparison.

Either both columns must be numerical, or they both must be strings. The comparison between strings is lexicographical. Comparison between complex types and array types are not supported.

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

References CPL_ERROR_INVALID_TYPE, cpl_table_select_row(), CPL_TYPE_COMPLEX, CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT, CPL_TYPE_LONG, CPL_TYPE_LONG_LONG, CPL_TYPE_POINTER, and CPL_TYPE_STRING.

## cpl_table_or_selected_double()

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

References cpl_table_select_row(), and CPL_TYPE_DOUBLE.

## cpl_table_or_selected_double_complex()

cpl_size cpl_table_or_selected_double_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_table_select_operator | operator,
|  | double complex | value )

Select from unselected table rows, by comparing double complex column values with a complex 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_COMPLEX.
  CPL_ERROR_ILLEGAL_INPUT | Operator other than CPL_EQUAL_TO or CPL_NOT_EQUAL_TO was specified.

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` and `CPL_NOT_EQUAL_TO`. 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_complex()`.

References CPL_ERROR_ILLEGAL_INPUT, cpl_table_select_row(), and CPL_TYPE_DOUBLE_COMPLEX.

## cpl_table_or_selected_float()

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

References cpl_table_select_row(), and CPL_TYPE_FLOAT.

## cpl_table_or_selected_float_complex()

cpl_size cpl_table_or_selected_float_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_table_select_operator | operator,
|  | float complex | value )

Select from unselected table rows, by comparing float complex column values with a complex 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_COMPLEX.
  CPL_ERROR_ILLEGAL_INPUT | Operator other than CPL_EQUAL_TO or CPL_NOT_EQUAL_TO was specified.

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` and `CPL_NOT_EQUAL_TO`. 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_complex()`.

References CPL_ERROR_ILLEGAL_INPUT, cpl_table_select_row(), and CPL_TYPE_FLOAT_COMPLEX.

## cpl_table_or_selected_int()

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

References cpl_table_select_row(), and CPL_TYPE_INT.

## cpl_table_or_selected_invalid()

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

References cpl_table_select_all(), cpl_table_select_row(), CPL_TYPE_POINTER, and CPL_TYPE_STRING.

## cpl_table_or_selected_long()

cpl_size cpl_table_or_selected_long | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_table_select_operator | operator,
|  | long | value )

Select from unselected table rows, by comparing long 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_LONG.

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

References cpl_table_select_row(), and CPL_TYPE_LONG.

## cpl_table_or_selected_long_long()

cpl_size cpl_table_or_selected_long_long | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_table_select_operator | operator,
|  | long long | value )

Select from unselected table rows, by comparing long long 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_LONG_LONG.

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

References cpl_table_select_row(), and CPL_TYPE_LONG_LONG.

## cpl_table_or_selected_string()

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

References CPL_ERROR_ILLEGAL_INPUT, cpl_table_select_row(), and CPL_TYPE_STRING.

## cpl_table_or_selected_window()

cpl_size cpl_table_or_selected_window | ( | cpl_table * | table,
|  | cpl_size | start,
|  | cpl_size | 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()`.

References cpl_calloc(), CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_table_select_all().

## cpl_table_power_column()

cpl_error_code cpl_table_power_column | ( | cpl_table * | table,
|  | const char * | name,
|  | double | exponent )

Compute the power of numerical column values.

Parameters

  table | Pointer to table.
  name | Name of column of numerical type
  exponent | Constant exponent.

Returns
  `CPL_ERROR_NONE` on success.

See also
  pow(), cpow()

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. For float and float complex the operation is performed in single precision, otherwise it is performed in double precision and then rounded if the column is of an integer type. Results that would or do cause domain errors or overflow are marked as invalid.

References CPL_ERROR_NONE.

## cpl_table_real_column()

cpl_error_code cpl_table_real_column | ( | cpl_table * | table,
|  | const char * | name )

Compute the real part value of table column elements.

Parameters

  table | Pointer to table.
  name | Column name.

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 neither numerical nor complex.

Each column element is replaced by its real party value only. Invalid elements are not modified by this operation. If the column is complex, its type will be turned to real (CPL_TYPE_FLOAT_COMPLEX will be changed into CPL_TYPE_FLOAT, and CPL_TYPE_DOUBLE_COMPLEX will be changed into CPL_TYPE_DOUBLE), and any pointer retrieved by calling `cpl_table_get_data_float_complex()`, `cpl_table_get_data_double_complex()`, etc., should be discarded.

References CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, cpl_table_get_column_type(), CPL_TYPE_COMPLEX, CPL_TYPE_DOUBLE, and CPL_TYPE_FLOAT.

## cpl_table_save()

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_UNSUPPORTED_MODE | A saving mode other than CPL_IO_CREATE and CPL_IO_EXTEND was specified.
  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_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_CREATE`, 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. If mode is set to `CPL_IO_APPEND` it is possible to add rows to the last FITS table extension of the output FITS file.

Note that the modes `CPL_IO_EXTEND` and `CPL_IO_APPEND` require that the target 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 on the system umask).

When using the mode `CPL_IO_APPEND` additional requirements must be fulfilled, which are that the column properties like type, format, units, etc. must match as the properties of the FITS table extension to which the rows should be added exactly. In particular this means that both tables use the same null value representation for integral type columns!

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_CREATE`, 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.

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` and `CPL_TYPE_LONG_LONG` are the only ones that need a specific code to be explicitly assigned to them. This can be realised by calling the functions cpl_table_fill_invalid_int() and cpl_table_fill_invalid_long_long(), respectively, for each table column of type `CPL_TYPE_INT` and `CPL_TYPE_LONG_LONG` 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.
  - Using the mode `CPL_IO_APPEND` requires that the column properties of the table to be appended are compared to the column properties of the target FITS extension for each call, which introduces a certain overhead. This means that appending a single table row at a time may not be efficient and is not recommended. Rather than writing one row at a time one should write table chunks containing a suitable number or rows.

References CPL_ERROR_NONE, and CPL_IO_APPEND.

## cpl_table_select_all()

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.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_free().

Referenced by cpl_table_erase_invalid(), cpl_table_erase_invalid_rows(), cpl_table_erase_selected(), cpl_table_erase_window(), cpl_table_insert(), cpl_table_insert_window(), cpl_table_or_selected_invalid(), cpl_table_or_selected_window(), cpl_table_set_size(), and cpl_table_shift_column().

## cpl_table_select_row()

cpl_error_code cpl_table_select_row | ( | cpl_table * | table,
|  | cpl_size | 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.

References cpl_calloc(), CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_free().

Referenced by cpl_table_or_selected(), cpl_table_or_selected_double(), cpl_table_or_selected_double_complex(), cpl_table_or_selected_float(), cpl_table_or_selected_float_complex(), cpl_table_or_selected_int(), cpl_table_or_selected_invalid(), cpl_table_or_selected_long(), cpl_table_or_selected_long_long(), and cpl_table_or_selected_string().

## cpl_table_set()

cpl_error_code cpl_table_set | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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, or it is of type array.

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.

References CPL_ERROR_NONE.

## cpl_table_set_array()

cpl_error_code cpl_table_set_array | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | const cpl_array * | array )

Write an array to an array table column element.

Parameters

  table | Pointer to table.
  name | Name of table column to access.
  row | Position where to write the array.
  array | Array 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 array.
  CPL_ERROR_INCOMPATIBLE_INPUT | The size of the input array is different from the depth of the specified column.

Write an array to a table column of type array. The written value can also be a `NULL` pointer, that is equivalent to a call to `cpl_table_set_invalid()`. Note that the array is copied, therefore the original can be modified without affecting the table element. To "plug" an array directly into a table element, use the function `cpl_table_get_data_array()`. Beware that the "plugged" array must have the same type and depth declared for the column.

References CPL_ERROR_NONE.

## cpl_table_set_column_depth()

cpl_error_code cpl_table_set_column_depth | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | depth )

Modify depth of a column of arrays.

Parameters

  table | Pointer to table.
  name | Column name.
  depth | New column depth.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | Any input argument is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The specified new depth is negative.
  CPL_ERROR_DATA_NOT_FOUND | A column with the specified name is not found in table.
  CPL_ERROR_TYPE_MISMATCH | The column with the specified name is not an array type.

This function is applicable just to columns of arrays. The contents of the arrays in the specified column will be unchanged up to the lesser of the new and old depths. If the depth is increased, the extra array elements would be flagged as invalid. The pointers to array data may change, therefore pointers previously retrieved by calling `cpl_array_get_data_int()`, `cpl_array_get_data_string()`, etc. should be discarded.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_TYPE_POINTER.

## cpl_table_set_column_dimensions()

cpl_error_code cpl_table_set_column_dimensions | ( | cpl_table * | table,
|  | const char * | name,
|  | const cpl_array * | dimensions )

Set the dimensions of a table column of arrays.

Parameters

  table | Pointer to table.
  name | Column name.
  dimensions | Integer array containing the sizes of the column dimensions

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_ILLEGAL_INPUT | Either the specified column is not of type array, or the dimensions array contains invalid elements.
  CPL_ERROR_TYPE_MISMATCH | The dimensions array is not of type CPL_TYPE_INT.
  CPL_ERROR_INCOMPATIBLE_INPUT | The specified dimensions are incompatible with the total number of elements in the column arrays.

Set the number of dimensions of a column. If the dimensions array has size less than 2, nothing is done and no error is returned.

References CPL_ERROR_NULL_INPUT.

## cpl_table_set_column_format()

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()`. This information is lost after saving the table in FITS format using `cpl_table_save()`.

References CPL_ERROR_NONE.

Referenced by cpl_table_copy_structure().

## cpl_table_set_column_invalid()

cpl_error_code cpl_table_set_column_invalid | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | start,
|  | cpl_size | 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 either a string or an array column, the corresponding strings or arrays 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.

References CPL_ERROR_NONE.

## cpl_table_set_column_unit()

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. It is however saved to a FITS file when using cpl_table_save().

References CPL_ERROR_NONE.

Referenced by cpl_table_copy_structure().

## cpl_table_set_complex()

cpl_error_code cpl_table_set_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | double complex | value )

Write a complex value to a complex 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 complex, or it is of type array.

Write a value to a complex 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.

References CPL_ERROR_NONE.

## cpl_table_set_double()

cpl_error_code cpl_table_set_double | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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()`.

References CPL_ERROR_NONE.

## cpl_table_set_double_complex()

cpl_error_code cpl_table_set_double_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | double complex | value )

Write a value to a double complex 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_COMPLEX.

Write a value to a table column of type `CPL_TYPE_DOUBLE_COMPLEX`. 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_complex()`.

References CPL_ERROR_NONE.

## cpl_table_set_float()

cpl_error_code cpl_table_set_float | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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()`.

References CPL_ERROR_NONE.

## cpl_table_set_float_complex()

cpl_error_code cpl_table_set_float_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | float complex | value )

Write a value to a float complex 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_COMPLEX.

Write a value to a table column of type `CPL_TYPE_FLOAT_COMPLEX`. 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_complex()`.

References CPL_ERROR_NONE.

## cpl_table_set_int()

cpl_error_code cpl_table_set_int | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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()`.

References CPL_ERROR_NONE.

## cpl_table_set_invalid()

cpl_error_code cpl_table_set_invalid | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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 either a string or an array column, the corresponding string or array is set free and its pointer is set to `NULL`. For other data types, the corresponding table element is flagged internally as invalid.

References CPL_ERROR_NONE.

Referenced by cpl_ppm_match_points().

## cpl_table_set_long()

cpl_error_code cpl_table_set_long | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | long | value )

Write a value to an long 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_LONG.

Write a value to a table column of type `CPL_TYPE_LONG`. 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()`.

References CPL_ERROR_NONE.

## cpl_table_set_long_long()

cpl_error_code cpl_table_set_long_long | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | row,
|  | long long | value )

Write a value to an long long 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_LONG_LONG.

Write a value to a table column of type `CPL_TYPE_LONG_LONG`. 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()`.

References CPL_ERROR_NONE.

## cpl_table_set_size()

cpl_error_code cpl_table_set_size | ( | cpl_table * | table,
|  | cpl_size | 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 set back to "all selected". 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.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_table_get_ncol(), and cpl_table_select_all().

Referenced by cpl_table_erase_selected().

## cpl_table_set_string()

cpl_error_code cpl_table_set_string | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | 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()`.

References CPL_ERROR_NONE.

## cpl_table_shift_column()

cpl_error_code cpl_table_shift_column | ( | cpl_table * | table,
|  | const char * | name,
|  | cpl_size | shift )

Shift the position of numeric or complex 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 neither numerical nor complex.
  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 and complex columns, and not to strings and or array types. The selection flags are always set back to "all selected" after this operation.

References CPL_ERROR_NONE, and cpl_table_select_all().

## cpl_table_sort()

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.
  CPL_ERROR_UNSUPPORTED_MODE | Any reference column specified in reflist is of type array.

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. The sorting is made in-place, therefore pointers to data retrieved with calls to `cpl_table_get_data_<TYPE>()` remain valid.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), cpl_malloc(), and cpl_propertylist_get_size().

## cpl_table_subtract_columns()

cpl_error_code cpl_table_subtract_columns | ( | cpl_table * | table,
|  | const char * | to_name,
|  | const char * | from_name )

Subtract two numeric or complex 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 neither numerical non complex, or it is an array column.

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.

References CPL_ERROR_NONE.

## cpl_table_subtract_scalar()

cpl_error_code cpl_table_subtract_scalar | ( | cpl_table * | table,
|  | const char * | name,
|  | double | value )

Subtract a constant value from a numerical or complex 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 neither numerical nor complex, or it is an array column.

See the description of the function `cpl_table_add_scalar()`.

References CPL_ERROR_NONE.

## cpl_table_subtract_scalar_complex()

cpl_error_code cpl_table_subtract_scalar_complex | ( | cpl_table * | table,
|  | const char * | name,
|  | double complex | value )

Subtract a constant complex value from a numerical or complex 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 neither numerical nor complex, or it is an array column.

See the description of the function `cpl_table_add_scalar_complex()`.

References CPL_ERROR_NONE.

## cpl_table_unselect_all()

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.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_free().

Referenced by cpl_table_and_selected(), cpl_table_and_selected_double(), cpl_table_and_selected_double_complex(), cpl_table_and_selected_float(), cpl_table_and_selected_float_complex(), cpl_table_and_selected_int(), cpl_table_and_selected_invalid(), cpl_table_and_selected_long(), cpl_table_and_selected_long_long(), and cpl_table_and_selected_string().

## cpl_table_unselect_row()

cpl_error_code cpl_table_unselect_row | ( | cpl_table * | table,
|  | cpl_size | 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.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_malloc().

Referenced by cpl_table_and_selected(), cpl_table_and_selected_double(), cpl_table_and_selected_double_complex(), cpl_table_and_selected_float(), cpl_table_and_selected_float_complex(), cpl_table_and_selected_int(), cpl_table_and_selected_invalid(), cpl_table_and_selected_long(), cpl_table_and_selected_long_long(), and cpl_table_and_selected_string().

## cpl_table_unwrap()

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.
  CPL_ERROR_UNSUPPORTED_MODE | The column with the given name is a column of arrays.

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

Note
  Columns of arrays cannot be unwrapped. Use the function `cpl_table_get_data_array()` to directly access the column data buffer.

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSUPPORTED_MODE, cpl_table_get_column_type(), and CPL_TYPE_POINTER.

## cpl_table_where_selected()

cpl_array * cpl_table_where_selected | ( | const cpl_table * | table | ) |

Get array of indexes to selected table rows.

Parameters

  table | Pointer to table.

Returns
  Indexes to selected table rows, or NULL in case of error.

Errors

  CPL_ERROR_NULL_INPUT | Input table is a NULL pointer.

Get array of indexes to selected table rows. If no rows are selected, an array of size zero is returned. The returned array must be deleted using `cpl_array_delete()`.

References cpl_array_fill_window(), cpl_array_get_data_cplsize(), cpl_array_new(), CPL_ERROR_NULL_INPUT, and CPL_TYPE_SIZE.

## cpl_table_wrap_double()

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.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_wrap_double_complex()

cpl_error_code cpl_table_wrap_double_complex | ( | cpl_table * | table,
|  | double complex * | data,
|  | const char * | name )

Create in table a new double complex column 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_COMPLEX` that will encapsulate the given data. See the description of `cpl_table_wrap_int()` for further details.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_wrap_float()

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.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_wrap_float_complex()

cpl_error_code cpl_table_wrap_float_complex | ( | cpl_table * | table,
|  | float complex * | data,
|  | const char * | name )

Create in table a new float complex 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_COMPLEX` that will encapsulate the given data. See the description of `cpl_table_wrap_int()` for further details.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_wrap_int()

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.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_wrap_long()

cpl_error_code cpl_table_wrap_long | ( | cpl_table * | table,
|  | long * | data,
|  | const char * | name )

Create in table a new long 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_LONG` that will encapsulate the given data. See the description of `cpl_table_wrap_int()` for further details.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_wrap_long_long()

cpl_error_code cpl_table_wrap_long_long | ( | cpl_table * | table,
|  | long long * | data,
|  | const char * | name )

Create in table a new long long 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_LONG_LONG` that will encapsulate the given data. See the description of `cpl_table_wrap_int()` for further details.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_table_wrap_string()

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.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.