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)

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.