Main Page   Modules   Alphabetical List   Compound List   Compound Members  

Columns


Functions

cpl_column * cpl_column_new_int (int length)
 Create a new integer column. More...

cpl_column * cpl_column_new_float (int length)
 Create a new float column. More...

cpl_column * cpl_column_new_double (int length)
 Create a new double column. More...

cpl_column * cpl_column_new_string (int length)
 Create a new string column. More...

cpl_column * cpl_column_new_from_data_int (int *data, int length)
 Create a new integer column from existing data. More...

cpl_column * cpl_column_new_from_data_float (float *data, int length)
 Create a new float column from existing data. More...

cpl_column * cpl_column_new_from_data_double (double *data, int length)
 Create a new double column from existing data. More...

cpl_column * cpl_column_new_from_data_string (char **data, int length)
 Create a new character string column from existing data. More...

cpl_error_code cpl_column_copy_data (cpl_column *column, double *data)
 Copy array of numerical data to a numerical column. More...

cpl_error_code cpl_column_copy_data_int (cpl_column *column, int *data)
 Copy existing data to an integer column. More...

cpl_error_code cpl_column_copy_data_float (cpl_column *column, float *data)
 Copy existing data to a float column. More...

cpl_error_code cpl_column_copy_data_double (cpl_column *column, double *data)
 Copy existing data to a double column. More...

cpl_error_code cpl_column_copy_data_string (cpl_column *column, char **data)
 Copy existing data to a string column. More...

void cpl_column_delete (cpl_column *column)
 Delete a column. More...

void cpl_column_delete_but_data (cpl_column *column)
 Delete a column, without losing the data. More...

void cpl_column_delete_but_strings (cpl_column *column)
 Delete a string column, without losing the single strings. More...

cpl_error_code cpl_column_set_name (cpl_column *column, const char *name)
 Give a new name to a column. More...

const char * cpl_column_get_name (cpl_column *column)
 Get the name of a column. More...

cpl_error_code cpl_column_set_unit (cpl_column *column, const char *unit)
 Give a new unit to a column. More...

const char * cpl_column_get_unit (cpl_column *column)
 Get the unit of a column. More...

cpl_error_code cpl_column_set_format (cpl_column *column, const char *format)
 Give a new format to a column. More...

const char * cpl_column_get_format (cpl_column *column)
 Get the format of a column. More...

int cpl_column_get_size (cpl_column *column)
 Get the length of a column. More...

cpl_type cpl_column_get_type (cpl_column *column)
 Get the type of a column. More...

int cpl_column_is_null (cpl_column *column, int row)
 Check if a column element is NULL. More...

int cpl_column_any_null (cpl_column *column)
 Check if a column contains at least one NULL value. More...

int cpl_column_any_valid (cpl_column *column)
 Check if a column contains at least one valid (i.e., not NULL) value. More...

int cpl_column_count_nulls (cpl_column *column)
 Count number of NULLs in a column. More...

int * cpl_column_get_data_int (cpl_column *column)
 Get a pointer to integer column data. More...

float * cpl_column_get_data_float (cpl_column *column)
 Get a pointer to float column data. More...

double * cpl_column_get_data_double (cpl_column *column)
 Get a pointer to double column data. More...

char ** cpl_column_get_data_string (cpl_column *column)
 Get a pointer to string column data. More...

cpl_column_flag * cpl_column_get_data_null (cpl_column *column)
 Get a pointer to a column null flags buffer. More...

cpl_error_code cpl_column_set_data_null (cpl_column *column, cpl_column_flag *nulls, int nullcount)
 Plug a new null buffer into a numerical column. More...

cpl_error_code cpl_column_resize (cpl_column *column, int new_length)
 Reallocate a column to a new number of elements. More...

double cpl_column_get (cpl_column *column, int row, int *null)
 Read a value from a numerical column. More...

int cpl_column_get_int (cpl_column *column, int row, int *null)
 Read a value from an integer column. More...

float cpl_column_get_float (cpl_column *column, int row, int *null)
 Read a value from a float column. More...

double cpl_column_get_double (cpl_column *column, int row, int *null)
 Read a value from a double column. More...

const char * cpl_column_get_string (cpl_column *column, int row)
 Read a value from a string column. More...

cpl_error_code cpl_column_set (cpl_column *column, int row, double value)
 Write a value to a numerical column element. More...

cpl_error_code cpl_column_set_int (cpl_column *column, int row, int value)
 Write a value to an integer column element. More...

cpl_error_code cpl_column_set_float (cpl_column *column, int row, float value)
 Write a value to a float column element. More...

cpl_error_code cpl_column_set_double (cpl_column *column, int row, double value)
 Write a value to a double column element. More...

cpl_error_code cpl_column_set_string (cpl_column *column, int row, const char *string)
 Write a character string to a string column element. More...

cpl_error_code cpl_column_set_null (cpl_column *column, int row)
 Set a column element to NULL;. More...

cpl_error_code cpl_column_fill (cpl_column *column, int start, int count, double value)
 Write a value to a numerical column segment. More...

cpl_error_code cpl_column_fill_int (cpl_column *column, int start, int count, int value)
 Write a value to an integer column segment. More...

cpl_error_code cpl_column_fill_float (cpl_column *column, int start, int count, float value)
 Write a value to a float column segment. More...

cpl_error_code cpl_column_fill_double (cpl_column *column, int start, int count, double value)
 Write a value to a double column segment. More...

cpl_error_code cpl_column_fill_string (cpl_column *column, int start, int count, const char *value)
 Write a string to a string column segment. More...

cpl_error_code cpl_column_fill_null (cpl_column *column, int start, int count)
 Set a column segment to NULL. More...

cpl_error_code cpl_column_copy_segment (cpl_column *column, int start, int count, double *values)
 Copy an array of values to a numerical column segment. More...

cpl_error_code cpl_column_copy_segment_int (cpl_column *column, int start, int count, int *values)
 Copy a list of integer values to an integer column segment. More...

cpl_error_code cpl_column_copy_segment_float (cpl_column *column, int start, int count, float *values)
 Copy a list of float values to a float column segment. More...

cpl_error_code cpl_column_copy_segment_double (cpl_column *column, int start, int count, double *values)
 Copy a list of double values to a double column segment. More...

cpl_error_code cpl_column_copy_segment_string (cpl_column *column, int start, int count, char **strings)
 Copy a list of strings to a string column segment. More...

cpl_error_code cpl_column_erase_segment (cpl_column *column, int start, int count)
 Delete a column segment. More...

cpl_error_code cpl_column_insert_segment (cpl_column *column, int start, int count)
 Insert a segment of NULLs into column data. More...

cpl_column * cpl_column_duplicate (cpl_column *column)
 Make a copy of a column. More...

cpl_column * cpl_column_convert_to_int (cpl_column *column)
 Cast a numerical column to a new integer column. More...

cpl_column * cpl_column_convert_to_float (cpl_column *column)
 Cast a numeric column to a new float column. More...

cpl_column * cpl_column_convert_to_double (cpl_column *column)
 Cast a numeric column to a new double column. More...

cpl_column * cpl_column_extract (cpl_column *column, int start, int count)
 Create a column from an interval of another column. More...

cpl_error_code cpl_column_merge (cpl_column *target_column, cpl_column *insert_column, int position)
 Insert a column into another column of the same type. More...

cpl_error_code cpl_column_add (cpl_column *to_column, cpl_column *from_column)
 Add two numerical columns. More...

cpl_error_code cpl_column_subtract (cpl_column *to_column, cpl_column *from_column)
 Subtract two numeric columns. More...

cpl_error_code cpl_column_multiply (cpl_column *to_column, cpl_column *from_column)
 Multiply two numeric columns. More...

cpl_error_code cpl_column_divide (cpl_column *to_column, cpl_column *from_column)
 Divide two numeric columns. More...

cpl_error_code cpl_column_const_op (cpl_column *column, double value, int operation)
 Arithmetic between a numerical column and a constant. More...

cpl_error_code cpl_column_logarithm (cpl_column *column, double base)
 Compute the logarithm of column values. More...

cpl_error_code cpl_column_exponential (cpl_column *column, double base)
 Compute the exponential of column values. More...

cpl_error_code cpl_column_power (cpl_column *column, double exponent)
 Compute a power of column values. More...

cpl_error_code cpl_column_add_constant (cpl_column *column, double value)
 Add a constant value to a numerical column. More...

cpl_error_code cpl_column_subtract_constant (cpl_column *column, double value)
 Subtract a constant value from a numerical column. More...

cpl_error_code cpl_column_multiply_constant (cpl_column *column, double value)
 Multiply by a constant a numerical column. More...

cpl_error_code cpl_column_divide_constant (cpl_column *column, double value)
 Divide by a constant a numerical column. More...

double cpl_column_mean (cpl_column *column)
 Compute the mean value of a numeric column. More...

double cpl_column_max (cpl_column *column)
 Get maximum value in a numerical column. More...

double cpl_column_min (cpl_column *column)
 Get minimum value in a numerical column. More...

cpl_error_code cpl_column_maxpos (cpl_column *column, int *row)
 Get position of maximum in a numerical column. More...

cpl_error_code cpl_column_minpos (cpl_column *column, int *row)
 Get position of minimum in a numerical column. More...

double cpl_column_median (cpl_column *column)
 Find the median of a numerical column. More...

cpl_error_code cpl_column_shift (cpl_column *column, int shift)
 Shift numeric column elements. More...

cpl_error_code cpl_column_code_null_int (cpl_column *column, int code)
 Write to NULL flagged integer column elements a numeric code. More...

cpl_error_code cpl_column_code_null_float (cpl_column *column, float code)
 Write to NULL flagged float column elements a numeric code. More...

cpl_error_code cpl_column_code_null_double (cpl_column *column, double code)
 Write to NULL flagged double column elements a numeric code. More...


Detailed Description

This module provides functions to create, destroy and use a cpl_column.
Synopsis:
   #include <cpl_column.h>

Function Documentation

cpl_error_code cpl_column_add cpl_column *    to_column,
cpl_column *    from_column
 

Add two numerical columns.

Parameters:
to_column  Target column.
from_column  Column to be summed to target column.
Returns:
0 on success. If the input columns do not have the same length, a CPL_ERROR_INCOMPATIBLE_INPUT is returned. If either or both column is of type string, a CPL_ERROR_INVALID_TYPE is returned.
The result of the sum is stored in the target colum. The two columns to add must have the same length. Their types may differ, and in that case the operation would be performed according to the C upcasting rules, with a final cast of the result to the target column type. NULL flags are also upgraded: if either or both members of the sum are NULLs, the result will be a NULL too. Underflows and overflows are ignored.

cpl_error_code cpl_column_add_constant cpl_column *    column,
double    value
 

Add a constant value to a numerical column.

Parameters:
column  Target column.
value  Value to add.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. NULL flags are not modified by this operation.

int cpl_column_any_null cpl_column *    column
 

Check if a column contains at least one NULL value.

Parameters:
column  Column to inquire.
Returns:
1 if the column contains at least one NULL, 0 if not.
Check if there are NULL values in a column.

int cpl_column_any_valid cpl_column *    column
 

Check if a column contains at least one valid (i.e., not NULL) value.

Parameters:
column  Column to inquire.
Returns:
1 if the column contains at least one valid value, 0 if not.
Check if there are valid values in a column.

cpl_error_code cpl_column_code_null_double cpl_column *    column,
double    code
 

Write to NULL flagged double column elements a numeric code.

Parameters:
column  Input column.
code  Code to write at NULL column elements.
Returns:
0 on success. If the accessed column is not double, a CPL_ERROR_TYPE_MISMATCH is returned.
In general the column elements that are flagged as NULLs may contain any value, that should not be given any meaning whatsoever. In order to export the column data (using a call to cpl_table_get_data_float() ) to procedures that are external to the CPL column system, it may turn out to be appropriate assigning to all NULL flagged elements a special code value. This code value will supposedly be recognized and handled properly by the foreign method. Note that only existing NULL elements will be coded as indicated: flagging with NULLs more column elements would leave their actual values still undefined. Also, any further processing of the table column would not take care of maintaining the assigned NULL code to a given NULL flagged column element: therefore the NULL code should be set just before it is actually needed.

cpl_error_code cpl_column_code_null_float cpl_column *    column,
float    code
 

Write to NULL flagged float column elements a numeric code.

Parameters:
column  Input column.
code  Code to write at NULL column elements.
Returns:
0 on success. If the accessed column is not float, a CPL_ERROR_TYPE_MISMATCH is returned.
In general the column elements that are flagged as NULLs may contain any value, that should not be given any meaning whatsoever. In order to export the column data (using a call to cpl_table_get_data_float() ) to procedures that are external to the CPL column system, it may turn out to be appropriate assigning to all NULL flagged elements a special code value. This code value will supposedly be recognized and handled properly by the foreign method. Note that only existing NULL elements will be coded as indicated: flagging with NULLs more column elements would leave their actual values still undefined. Also, any further processing of the table column would not take care of maintaining the assigned NULL code to a given NULL flagged column element: therefore the NULL code should be set just before it is actually needed.

cpl_error_code cpl_column_code_null_int cpl_column *    column,
int    code
 

Write to NULL flagged integer column elements a numeric code.

Parameters:
column  Input column.
code  Code to write at NULL column elements.
Returns:
0 on success. If the accessed column is not integer, a CPL_ERROR_TYPE_MISMATCH is returned.
In general the column elements that are flagged as NULLs may contain any value, that should not be given any meaning whatsoever. In order to export the column data (using a call to cpl_table_get_data_int() ) to procedures that are external to the CPL column system, it may turn out to be appropriate assigning to all NULL flagged elements a special code value. This code value will supposedly be recognized and handled properly by the foreign method. Note that only existing NULL elements will be coded as indicated: flagging with NULLs more column elements would leave their actual values still undefined. Also, any further processing of the table column would not take care of maintaining the assigned NULL code to a given NULL flagged column element: therefore the NULL code should be set just before it is actually needed.

cpl_error_code cpl_column_const_op cpl_column *    column,
double    value,
int    operation
 

Arithmetic between a numerical column and a constant.

Parameters:
column  Target column.
value  Constant operand.
operation  Operation to perform.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned. If a not supported operation is specified, a CPL_ERROR_UNSUPPORTED_MODE is returned. If the specified constant is zero, and the specified operation is division, a CPL_ERROR_DIVISION_BY_ZERO is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. NULL flags are not modified by this operation. Possible operations are:

'+' Addition '-' Subtraction '*' Multiplication '/' Division 'l' Logarithm '^' Power 'e' Exponentiation

When logarithm or exponentiation are computed, the passed constant represents the base of the logarithm or of the exponentiation operation.

cpl_column* cpl_column_convert_to_double cpl_column *    column
 

Cast a numeric column to a new double column.

Parameters:
column  Column to be cast.
Returns:
Pointer to the new columnm, or NULL. The latter happens if the accessed column is of type string, and in that case a CPL_ERROR_INVALID_TYPE is set.
If the input column is also double, a simple copy is made. The output column is nameless, unitless, and with a default format. If the input column is NULL, as in the case of any other error, a NULL is returned.

cpl_column* cpl_column_convert_to_float cpl_column *    column
 

Cast a numeric column to a new float column.

Parameters:
column  Column to be cast.
Returns:
Pointer to the new columnm, or NULL. The latter happens if the accessed column is of type string, and in that case a CPL_ERROR_INVALID_TYPE is set.
If the input column is also float, a simple copy is made. The output column is nameless, unitless, and with a default format. If the input column is NULL, as in the case of any other error, a NULL is returned.

cpl_column* cpl_column_convert_to_int cpl_column *    column
 

Cast a numerical column to a new integer column.

Parameters:
column  Column to be cast.
Returns:
Pointer to the new columnm, or NULL. The latter happens if the accessed column is of type string, and in that case a CPL_ERROR_INVALID_TYPE is set.
If the input column is also integer, a simple copy is made. The output column is nameless, unitless, and with a default format. In case of error, a NULL is returned.

cpl_error_code cpl_column_copy_data cpl_column *    column,
double *    data
 

Copy array of numerical data to a numerical column.

Parameters:
column  Existing column.
data  Existing data buffer.
Returns:
0 on success. If the column is not a numerical column, a CPL_ERROR_INVALID_TYPE is returned.
The input data are copied into the specified column. If the type of the accessed column is not double, data values will be truncated according to C casting rules. The size of the input array is not checked in any way, and the data values are all considered valid: NULL values should be marked using the functions * cpl_column_set_null() and cpl_column_fill_null().

cpl_error_code cpl_column_copy_data_double cpl_column *    column,
double *    data
 

Copy existing data to a double column.

Parameters:
column  Existing column.
data  Existing data buffer.
Returns:
0 on success. If the input column is not double, a CPL_ERROR_TYPE_MISMATCH is returned.
The input data are copied into the specified column. The size of the input array is not checked in any way, and the data values are all considered valid: NULL values should be marked using the functions cpl_column_set_null() and cpl_column_fill_null().

cpl_error_code cpl_column_copy_data_float cpl_column *    column,
float *    data
 

Copy existing data to a float column.

Parameters:
column  Existing column.
data  Existing data buffer.
Returns:
0 on success. If the input column is not float, a CPL_ERROR_TYPE_MISMATCH is returned.
The input data are copied into the specified column. The size of the input array is not checked in any way, and the data values are all considered valid: NULL values should be marked using the functions cpl_column_set_null() and cpl_column_fill_null().

cpl_error_code cpl_column_copy_data_int cpl_column *    column,
int *    data
 

Copy existing data to an integer column.

Parameters:
column  Existing column.
data  Existing data buffer.
Returns:
0 on success. If the input column is not integer, a CPL_ERROR_TYPE_MISMATCH is returned.
The input data are copied into the specified column. The size of the input array is not checked in any way, and the data values are all considered valid: NULL values should be marked using the functions cpl_column_set_null() and cpl_column_fill_null().

cpl_error_code cpl_column_copy_data_string cpl_column *    column,
char **    data
 

Copy existing data to a string column.

Parameters:
column  Existing column.
data  Existing data buffer.
Returns:
0 on success. If the input column is not of type string, a CPL_ERROR_TYPE_MISMATCH is returned.
The input data are copied into the specified column. The size of the input array is not checked in any way. The pointed strings are all duplicated, while overwritten strings are released.

cpl_error_code cpl_column_copy_segment cpl_column *    column,
int    start,
int    count,
double *    values
 

Copy an array of values to a numerical column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write values.
count  Number of values to write.
values  Values to write.
Returns:
0 on success. If the accessed column is not of numerical type, a CPL_ERROR_INVALID_TYPE is set.
Write an array of values to a numerical column segment. The values are cast to the accessed column type. The written values are automatically marked as valid.

cpl_error_code cpl_column_copy_segment_double cpl_column *    column,
int    start,
int    count,
double *    values
 

Copy a list of double values to a double column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write values.
count  Number of values to write.
values  Values to write.
Returns:
0 on success. If the accessed column is not of double type, a CPL_ERROR_TYPE_MISMATCH is set.
Write a list of double values to a double column segment. Internal conversion is not supported (if column is not double, this is an error). The written values are automatically marked as valid.

cpl_error_code cpl_column_copy_segment_float cpl_column *    column,
int    start,
int    count,
float *    values
 

Copy a list of float values to a float column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write values.
count  Number of values to write.
values  Values to write.
Returns:
0 on success. If the accessed column is not of float type, a CPL_ERROR_TYPE_MISMATCH is set.
Write a list of float values to a float column segment. Internal conversion is not supported (if column is not float, this is an error). The written values are automatically marked as valid.

cpl_error_code cpl_column_copy_segment_int cpl_column *    column,
int    start,
int    count,
int *    values
 

Copy a list of integer values to an integer column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write values.
count  Number of values to write.
values  Values to write.
Returns:
0 on success. If the accessed column is not of integer type, a CPL_ERROR_TYPE_MISMATCH is set.
Write a list of integer values to an integer column segment. Internal conversion is not supported (if column is not integer, this is an error). The written values are automatically marked as valid.

cpl_error_code cpl_column_copy_segment_string cpl_column *    column,
int    start,
int    count,
char **    strings
 

Copy a list of strings to a string column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write strings.
count  Number of strings to write.
strings  Strings to write.
Returns:
0 on success. If the accessed column is not of string type, a CPL_ERROR_TYPE_MISMATCH is set.
Write a list of strings values to a string column segment. Internal conversion is not supported (if column is not string, this is an error).

int cpl_column_count_nulls cpl_column *    column
 

Count number of NULLs in a column.

Parameters:
column  Column to inquire.
Returns:
Number of NULLs in a column.
Count number of NULLs in a valid column. If the column itself is a NULL, zero is returned.

void cpl_column_delete cpl_column *    column
 

Delete a column.

Parameters:
column  Column to be deleted.
Returns:
Nothing.
This function deletes a column. If the input column is NULL, nothing is done.

void cpl_column_delete_but_data cpl_column *    column
 

Delete a column, without losing the data.

Parameters:
column  Column to be deleted.
Returns:
Nothing.
This function deletes a column, but the data buffer is not destroyed. Supposedly, the developer knows that the data are static, or the developer holds the pointer to the data obtained with the functions cpl_column_get_data_int(), cpl_column_get_data_float(), etc. If the input column is NULL, nothing is done.

void cpl_column_delete_but_strings cpl_column *    column
 

Delete a string column, without losing the single strings.

Parameters:
column  Column to be deleted.
Returns:
Nothing, but if the column is not of string type, a CPL_ERROR_INVALID_TYPE is set.
This function deletes a string column, but the single strings pointed by the data buffer are not destroyed. Supposedly, the developer knows that the strings are static, or the developer holds the pointers to the strings somewhere else. If the input column is NULL, or the input column is not a string column, nothing is done.

cpl_error_code cpl_column_divide cpl_column *    to_column,
cpl_column *    from_column
 

Divide two numeric columns.

Parameters:
to_column  Target column.
from_column  Divisor column.
Returns:
0 on success. If the input columns do not have the same length, a CPL_ERROR_INCOMPATIBLE_INPUT is returned. If either or both column is of type string, a CPL_ERROR_INVALID_TYPE is returned.
The result of the division is stored in the target colum. The two columns must have the same length. Their types may differ, and in that case the operation would be performed according to the C upcasting rules, with a final cast of the result to the target column type. NULL flags are also upgraded: if either or both members of the division are NULLs, the result will be a NULL too. Underflows and overflows are ignored, but a division by zero is flagged by a NULL.

cpl_error_code cpl_column_divide_constant cpl_column *    column,
double    value
 

Divide by a constant a numerical column.

Parameters:
column  Target column.
value  Divisor.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned. If the input value is zero, a CPL_ERROR_DIVISION_BY_ZERO is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. NULL flags are not modified by this operation. If the divisor is zero, a failure is returned.

cpl_column* cpl_column_duplicate cpl_column *    column
 

Make a copy of a column.

Parameters:
column  Column to be duplicated.
Returns:
Pointer to the new columnm. Currently this function always succeeds.
If the input column is NULL, as in case of any other error, a NULL is returned. Copy is "in depth": in the case of a string column, also the string elements are duplicated.

cpl_error_code cpl_column_erase_segment cpl_column *    column,
int    start,
int    count
 

Delete a column segment.

Parameters:
column  Column to be accessed.
start  Position of first column element to delete.
count  Number of column elements to delete.
Returns:
0 on success. An attempt to delete all columns elements causes a CPL_ERROR_ILLEGAL_INPUT to be returned.
Delete a column segment. This is different from setting a column data segment to NULL, as done by cpl_column_fill_null(): here a portion of the data is physically removed, and the column data buffer shortened proportionally. The pointer to data may change (therefore pointers previously retrieved by calling cpl_column_get_data_int(), cpl_column_get_data_string(), etc., should be discarded). The specified segment can go beyond the end of the column, but to remove all column data element is flagged as an error, because zero length columns are illegal: in this case a column destructor should be called instead.

cpl_error_code cpl_column_exponential cpl_column *    column,
double    base
 

Compute the exponential of column values.

Parameters:
column  Target column.
base  Exponential base.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. The base must be positive, or an error will be generated.

cpl_column* cpl_column_extract cpl_column *    column,
int    start,
int    count
 

Create a column from an interval of another column.

Parameters:
column  Input column.
start  First element to be copied to new column.
count  Number of elements to be copied.
Returns:
Pointer to the new column. Currently this function always succeeds.
If start + count goes beyond the end of the input column, elements are always copied up to the end. The new column is nameless, but it inherits the unit and the format of the source column. Existing NULL flags are also transferred to the new column. If the input column is NULL, as in the case of any other error, a NULL is returned.

cpl_error_code cpl_column_fill cpl_column *    column,
int    start,
int    count,
double    value
 

Write a value to a numerical column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write value.
count  Number of values to write.
value  Value to write.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned.
Write the same value to a numerical column segment. The value is cast to the accessed column type. The written value is automatically marked as valid. To set a column interval to NULL use cpl_column_fill_null() instead.

cpl_error_code cpl_column_fill_double cpl_column *    column,
int    start,
int    count,
double    value
 

Write a value to a double column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write value.
count  Number of values to write.
value  Value to write.
Returns:
0 on success. If the accessed column is not double, a CPL_ERROR_TYPE_MISMATCH is returned.
Write the same value to a double column segment. Internal conversion is not supported (if column is not double, this is an error). The written value is automatically marked as valid. To set a column interval to NULL use cpl_column_fill_null() instead.

cpl_error_code cpl_column_fill_float cpl_column *    column,
int    start,
int    count,
float    value
 

Write a value to a float column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write value.
count  Number of values to write.
value  Value to write.
Returns:
0 on success. If the accessed column is not float, a CPL_ERROR_TYPE_MISMATCH is returned.
Write the same value to a float column segment. Internal conversion is not supported (if column is not float, this is an error). The written value is automatically marked as valid. To set a column interval to NULL use cpl_column_fill_null() instead.

cpl_error_code cpl_column_fill_int cpl_column *    column,
int    start,
int    count,
int    value
 

Write a value to an integer column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write value.
count  Number of values to write.
value  Value to write.
Returns:
0 on success. If the accessed column is not integer, a CPL_ERROR_TYPE_MISMATCH is returned.
Write the same value to an integer column segment. Internal conversion is not supported (if column is not integer, this is an error). The written value is automatically marked as valid. To set a column interval to NULL use cpl_column_fill_null() instead.

cpl_error_code cpl_column_fill_null cpl_column *    column,
int    start,
int    count
 

Set a column segment to NULL.

Parameters:
column  Column to be accessed.
start  Position where to start writing NULLs.
count  Number of column elements to set to NULL.
Returns:
0 on success. Currently this function always succeeds.
In the case of a string column, the corresponding strings are set free and their pointers are set to NULL; for other data types, the corresponding elements of the null flags buffer are flagged.

cpl_error_code cpl_column_fill_string cpl_column *    column,
int    start,
int    count,
const char *    value
 

Write a string to a string column segment.

Parameters:
column  Column to be accessed.
start  Position where to begin write value.
count  Number of values to write.
value  Value to write.
Returns:
0 on success. If the accessed column is not of type string, a CPL_ERROR_TYPE_MISMATCH is returned.
Copy the same string to a string column segment. Internal conversion is not supported (if column is not string, this is an error). If the input string is not a NULL, it is duplicated for each accessed column element. If the input string is NULL, this call is equivalent to cpl_column_fill_null().

double cpl_column_get cpl_column *    column,
int    row,
int *    null
 

Read a value from a numerical column.

Parameters:
column  Column to be accessed.
row  Position of element to be read.
null  Flag indicating null values, or error condition.
Returns:
Value read. A CPL_ERROR_INVALID_TYPE is set in case a non-numerical column is accessed.
Read a value from a numerical column. In case of error, or of NULL column element, the returned value is always set to zero. A null flag is used to indicate whether the accessed column element is a NULL (1) or not (0). The null flag signals also possible error conditions (-1), as using a column that is not numerical. The null flag address can also be NULL, and in that case the null flag will not be used. Column elements are counted starting from zero.

double* cpl_column_get_data_double cpl_column *    column
 

Get a pointer to double column data.

Parameters:
column  Column to get the data from.
Returns:
Pointer to double column data, or NULL. The latter case can occur only if the column is not of double type, therefore a CPL_ERROR_TYPE_MISMATCH is set.
Return a pointer to double column data. If the column contains no data, a NULL is returned. Use at your own risk: direct manipulation of column data rules out any check performed by the column object interface, and may introduce inconsistencies between the column information maintained internally and the actual column data.

float* cpl_column_get_data_float cpl_column *    column
 

Get a pointer to float column data.

Parameters:
column  Column to get the data from.
Returns:
Pointer to float column data, or NULL. The latter case can occur only if the column is not of float type, therefore a CPL_ERROR_TYPE_MISMATCH is set.
Return a pointer to float column data. If the column contains no data, a NULL is returned. Use at your own risk: direct manipulation of column data rules out any check performed by the column object interface, and may introduce inconsistencies between the column information maintained internally and the actual column data.

int* cpl_column_get_data_int cpl_column *    column
 

Get a pointer to integer column data.

Parameters:
column  Column to get the data from.
Returns:
Pointer to integer column data, or NULL. The latter case can occur only if the column is not of integer type, therefore a CPL_ERROR_TYPE_MISMATCH is set.
Return a pointer to integer column data. If column contains no data, a NULL is returned. Use at your own risk: direct manipulation of column data rules out any check performed by the column object interface, and may introduce inconsistencies between the column information maintained internally and the actual column data.

cpl_column_flag* cpl_column_get_data_null cpl_column *    column
 

Get a pointer to a column null flags buffer.

Parameters:
column  Column to get the data from.
Returns:
Pointer to the column null flags buffer, or NULL.
If all or no column elements are NULL, a NULL pointer is returned. A NULL is returned also if the column is of type CPL_TYPE_STRING (no null flags array is available in this case). Use at your own risk: direct manipulation of column data rules out any check performed by the column object interface, and may introduce inconsistencies between the column information maintained internally and the actual column data.

char** cpl_column_get_data_string cpl_column *    column
 

Get a pointer to string column data.

Parameters:
column  Column to get the data from.
Returns:
Pointer to string column data, or NULL. The latter case can occur only if the column is not of string type, therefore a CPL_ERROR_TYPE_MISMATCH is set.
Return a pointer to string column data. If the column contains no data, a NULL is returned. Use at your own risk: direct manipulation of column data rules out any check performed by the column object interface, and may introduce inconsistencies between the column information maintained internally and the actual column data.

double cpl_column_get_double cpl_column *    column,
int    row,
int *    null
 

Read a value from a double column.

Parameters:
column  Column to be accessed.
row  Position of element to be read.
null  Flag indicating null values, or error condition.
Returns:
Double value read. A CPL_ERROR_TYPE_MISMATCH is set if the accessed column is not of double type.
Read a value from a double column. Internal conversion is not provided (if column is not double, this is an error). In case of error, or of NULL column element, the returned value is always set to zero. A null flag is used to indicate whether the accessed column element is a NULL (1) or not (0). The null flag signals also possible error conditions (-1), as using a column that is not double. The null flag address can also be NULL, and in that case the null flag will not be used. Column elements are counted starting from zero.

float cpl_column_get_float cpl_column *    column,
int    row,
int *    null
 

Read a value from a float column.

Parameters:
column  Column to be accessed.
row  Position of element to be read.
null  Flag indicating null values, or error condition.
Returns:
Float value read. A CPL_ERROR_TYPE_MISMATCH is set if the accessed column is not of float type.
Read a value from a float column. Internal conversion is not provided (if column is not float, this is an error). In case of error, or of NULL column element, the returned value is always set to zero. A null flag is used to indicate whether the accessed column element is a NULL (1) or not (0). The null flag signals also possible error conditions (-1), as using a column that is not float. The null flag address can also be NULL, and in that case the null flag will not be used. Column elements are counted starting from zero.

const char* cpl_column_get_format cpl_column *    column
 

Get the format of a column.

Parameters:
column  Column to get the format from.
Returns:
Column format, or NULL. The latter case can occur only if a NULL column is passed to the function, and a CPL_ERROR_NULL_INPUT is set.
Return the format string 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, if a real copy of a column format is required, this function should be called as an argument of the function strdup(). The function accepts also a NULL input column.

int cpl_column_get_int cpl_column *    column,
int    row,
int *    null
 

Read a value from an integer column.

Parameters:
column  Column to be accessed.
row  Position of element to be read.
null  Flag indicating null values, or error condition.
Returns:
Integer value read. A CPL_ERROR_TYPE_MISMATCH is set if the accessed column is not of integer type.
Read a value from an integer column. Internal conversion is not provided (if column is not integer, this is an error). In case of error, or of NULL column element, the returned value is always set to zero. A null flag is used to indicate whether the accessed column element is a NULL (1) or not (0). The null flag signals also possible error conditions (-1), as using a column that is not integer. The null flag address can also be NULL, and in that case the null flag will not be used. Column elements are counted starting from zero.

const char* cpl_column_get_name cpl_column *    column
 

Get the name of a column.

Parameters:
column  Column to get the name from.
Returns:
Name of column, or NULL if the column is nameless, or if the input column is a NULL. In the latter case, a CPL_ERROR_NULL_INPUT is set.
Return the name of a column, if present. Note that the returned string is a pointer to the column name, not its copy. Its manipulation will directly affect the column name, while changing the column name using cpl_column_set_name() will 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(). If the input column has no name, a NULL is returned. The function accepts also a NULL input column.

int cpl_column_get_size cpl_column *    column
 

Get the length of a column.

Parameters:
column  Column to get the length from.
Returns:
Length of column, or zero. The latter case can occur only if a NULL column is passed to the function, and a CPL_ERROR_NULL_INPUT is set.
If the column is NULL, zero is returned.

const char* cpl_column_get_string cpl_column *    column,
int    row
 

Read a value from a string column.

Parameters:
column  Column to be accessed.
row  Position of element to be read.
Returns:
Character string read. A CPL_ERROR_TYPE_MISMATCH is set if the accessed column is not of string type.
Return an element of a string column. Internal conversion is not provided (if column is not string, this is an error). If the column element is a NULL string, and in case of error, the returned value is always set to NULL. Note that the returned string is a pointer to a column element, not its copy. Its manipulation will directly affect that column element, while changing that column element using cpl_column_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(). Column elements are counted starting from zero.

cpl_type cpl_column_get_type cpl_column *    column
 

Get the type of a column.

Parameters:
column  Column to get the type from.
Returns:
Type of column, or CPL_TYPE_INVALID. The latter case can occur only if a NULL column is passed to the function, and a CPL_ERROR_NULL_INPUT is set.
If the column is NULL, CPL_TYPE_INVALID is returned.

const char* cpl_column_get_unit cpl_column *    column
 

Get the unit of a column.

Parameters:
column  Column to get the unit from.
Returns:
Unit of column, or NULL if the column is unitless, or if the input column is a NULL. In the latter case, a CPL_ERROR_NULL_INPUT is set.
Return the unit of a column, if present. Note that the returned string is a pointer to the column unit, not its copy. Its manipulation will directly affect the column unit, while changing the column unit using cpl_column_set_unit() will turn it into garbage. Therefore, if a real copy of a column unit is required, this function should be called as an argument of the function strdup(). If the input column has no unit, a NULL is returned. The function accepts also a NULL input column.

cpl_error_code cpl_column_insert_segment cpl_column *    column,
int    start,
int    count
 

Insert a segment of NULLs into column data.

Parameters:
column  Column to be accessed.
start  Column element where to insert the NULL segment.
count  Length of NULL segment.
Returns:
0 on success. Currently this function always succeeds.
Inserting a segment of NULLs in column data buffer is different from setting a column data segment to NULL, as done by cpl_column_fill_null(): here a portion of new data is physically inserted, and the column data buffer lengthened proportionally. Setting start to a number greater than the column length is legal, and has the effect of appending NULLs at the end of the column (equivalent to expanding a column using cpl_column_resize() ). The pointer to data may change, therefore pointers previously retrieved by calling cpl_column_get_data_int(), cpl_column_get_data_string(), etc., should be discarded.

int cpl_column_is_null cpl_column *    column,
int    row
 

Check if a column element is NULL.

Parameters:
column  Column to inquire.
row  Column element to inquire.
Returns:
1 if the column element is NULL, 0 if not.
Check if a column element is NULL. Column elements are counted starting from zero.

cpl_error_code cpl_column_logarithm cpl_column *    column,
double    base
 

Compute the logarithm of column values.

Parameters:
column  Target column.
base  Logarithm base.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. Non-positive column values will be turned to null.

double cpl_column_max cpl_column *    column
 

Get maximum value in a numerical column.

Parameters:
column  Input column.
Returns:
Maximum value. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is set. If the input column elements are all NULLs, a CPL_ERROR_DATA_NOT_FOUND is returned.
Column values flagged as NULLs are excluded from the search. A column just consisting of NULLs is forbidden. In case of error, the value returned by the function is always zero.

cpl_error_code cpl_column_maxpos cpl_column *    column,
int *    row
 

Get position of maximum in a numerical column.

Parameters:
column  Input column.
row  Returned position of maximum value.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is set. If the input column elements are all NULLs, a CPL_ERROR_DATA_NOT_FOUND is returned.
Column values flagged as NULLs are excluded from the search. A column just consisting of NULLs is forbidden. Argument row will be assigned the position of the maximum value, where rows are counted starting from 0. If more than one column element correspond to the max value, the position with the lowest row number is returned. In case of error, row is left untouched.

double cpl_column_mean cpl_column *    column
 

Compute the mean value of a numeric column.

Parameters:
column  Input column.
Returns:
Mean value. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is set. If the input column elements are all NULLs, a CPL_ERROR_DATA_NOT_FOUND is returned.
The returned value is always a double, independently on the column numerical type. Column values flagged as NULLs are excluded from the computation. The column must contain at least one non-NULL value. In case of error zero is always returned.

double cpl_column_median cpl_column *    column
 

Find the median of a numerical column.

Parameters:
column  Input column.
Returns:
Median. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is set. If the input column elements are all NULLs, a CPL_ERROR_DATA_NOT_FOUND is returned.
Column values flagged as NULLs are excluded from the search. The column must contain at least one non-NULL value. In case of failure, zero is returned.

cpl_error_code cpl_column_merge cpl_column *    target_column,
cpl_column *    insert_column,
int    position
 

Insert a column into another column of the same type.

Parameters:
target_column  Target column.
insert_column  Column to be inserted in target column.
position  Position of target where to insert.
Returns:
0 on success. If the columns are not of the same type, a CPL_ERROR_TYPE_MISMATCH is returned.
The first element of the column to be inserted will be at the specified position. If the specified position is greater than the target column length, the second column will be appended to the target column. The pointer to target data may change, therefore pointers previously retrieved by calling cpl_column_get_data_int(), cpl_column_get_data_string(), etc., should be discarded).

double cpl_column_min cpl_column *    column
 

Get minimum value in a numerical column.

Parameters:
column  Input column.
Returns:
Minimum value. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is set. If the input column elements are all NULLs, a CPL_ERROR_DATA_NOT_FOUND is returned.
Column values flagged as NULLs are excluded from the search. A column just consisting of NULLs is forbidden. In case of error, the value returned by the function is always zero.

cpl_error_code cpl_column_minpos cpl_column *    column,
int *    row
 

Get position of minimum in a numerical column.

Parameters:
column  Input column.
row  Returned position of minimum value.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is set. If the input column elements are all NULLs, a CPL_ERROR_DATA_NOT_FOUND is returned.
Column values flagged as NULLs are excluded from the search. A column just consisting of NULLs is forbidden. Argument row will be assigned the position of the minimum value, where rows are counted starting from 0. If more than one column element correspond to the min value, the position with the lowest row number is returned. In case of error, row is left untouched.

cpl_error_code cpl_column_multiply cpl_column *    to_column,
cpl_column *    from_column
 

Multiply two numeric columns.

Parameters:
to_column  Target column.
from_column  Multiplier column.
Returns:
0 on success. If the input columns do not have the same length, a CPL_ERROR_INCOMPATIBLE_INPUT is returned. If either or both column is of type string, a CPL_ERROR_INVALID_TYPE is returned.
The result of the multiplication is stored in the target colum. The two columns to multiply must have the same length. Their types may differ, and in that case the operation would be performed according to the C upcasting rules, with a final cast of the result to the target column type. NULL flags are also upgraded: if either or both members of the multiplication are NULLs, the result will be a NULL too. Underflows and overflows are ignored.

cpl_error_code cpl_column_multiply_constant cpl_column *    column,
double    value
 

Multiply by a constant a numerical column.

Parameters:
column  Target column.
value  Multiplier.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. NULL flags are not modified by this operation.

cpl_column* cpl_column_new_double int    length
 

Create a new double column.

Parameters:
length  Number of elements in column.
Returns:
Pointer to the new column, or NULL.
The function allocates memory for a column, its type is assigned, and its number of elements is allocated. All column elements are flagged as NULL.

cpl_column* cpl_column_new_float int    length
 

Create a new float column.

Parameters:
length  Number of elements in column.
Returns:
Pointer to the new column, or NULL.
The function allocates memory for a column, its type is assigned, and its number of elements is allocated. All column elements are flagged as NULL.

cpl_column* cpl_column_new_from_data_double double *    data,
int    length
 

Create a new double column from existing data.

Parameters:
data  Existing data buffer.
length  Number of elements in column.
Returns:
Pointer to the new column, or NULL.
This function creates a new double column that will encapsulate the given data. Note that the size of the data array is not checked in any way, and that the data values are all considered valid: NULL values should be marked using the functions cpl_column_set_null() and cpl_column_fill_null(). The data array is not copied, so it should never be deallocated: to deallocate it, the function cpl_column_delete() should be called instead.

Note:
Functions that handle columns assume that a column data array is dinamically allocated: with a statically allocated array any function implying memory handling (cpl_column_resize(), cpl_column_delete(), etc.) would crash the program. This means that a static array should never be passed to this function.

cpl_column* cpl_column_new_from_data_float float *    data,
int    length
 

Create a new float column from existing data.

Parameters:
data  Existing data buffer.
length  Number of elements in column.
Returns:
Pointer to the new column, or NULL.
This function creates a new float column that will encapsulate the given data. Note that the size of the data array is not checked in any way, and that the data values are all considered valid: NULL values should be marked using the functions cpl_column_set_null() and cpl_column_fill_null(). The data array is not copied, so it should never be deallocated: to deallocate it, the function cpl_column_delete() should be called instead.

Note:
Functions that handle columns assume that a column data array is dinamically allocated: with a statically allocated array any function implying memory handling (cpl_column_resize(), cpl_column_delete(), etc.) would crash the program. This means that a static array should never be passed to this function.

cpl_column* cpl_column_new_from_data_int int *    data,
int    length
 

Create a new integer column from existing data.

Parameters:
data  Existing data buffer.
length  Number of elements in column.
Returns:
Pointer to the new column, or NULL.
This function creates a new integer column that will encapsulate the given data. Note that the size of the data array is not checked in any way, and that the data values are all considered valid: NULL values should be marked using the functions cpl_column_set_null() and cpl_column_fill_null(). The data array is not copied, so it should never be deallocated: to deallocate it, the function cpl_column_delete() should be called instead.

Note:
Functions that handle columns assume that a column data array is dinamically allocated: with a statically allocated array any function implying memory handling (cpl_column_resize(), cpl_column_delete(), etc.) would crash the program. This means that a static array should never be passed to this function.

cpl_column* cpl_column_new_from_data_string char **    data,
int    length
 

Create a new character string column from existing data.

Parameters:
data  Existing data buffer.
length  Number of elements in column.
Returns:
Pointer to the new column, or NULL.
This function creates a new string column that will encapsulate the given data. Note that the size of the data array is not checked in any way. The data array and the strings it points to are not copied, so they should never be deallocated: to deallocate them, the function cpl_delete_column() should be called instead. To deallocate single strings, cpl_column_set_null() and cpl_column_fill_null() should be used.

Note:
Functions that handle table columns assume that a column data array is dinamically allocated: with a statically allocated array any function implying memory handling (cpl_column_resize(), cpl_column_delete(), etc.) would crash the program. This means that a static array, or any array of pointers to static char, should never be passed to this function.

cpl_column* cpl_column_new_int int    length
 

Create a new integer column.

Parameters:
length  Number of elements in column.
Returns:
Pointer to the new column, or NULL.
The function allocates memory for a column, its type is assigned, and its number of elements is allocated. All column elements are flagged as NULL.

cpl_column* cpl_column_new_string int    length
 

Create a new string column.

Parameters:
length  Number of elements in column.
Returns:
Pointer to the new column, or NULL.
The function allocates memory for a column of pointers to char, all initialized to NULL. No memory is allocated for the single column elements.

cpl_error_code cpl_column_power cpl_column *    column,
double    exponent
 

Compute a power of column values.

Parameters:
column  Target column.
exponent  Constant exponent.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. Non-positive column values will be turned to null.

cpl_error_code cpl_column_resize cpl_column *    column,
int    new_length
 

Reallocate a column to a new number of elements.

Parameters:
column  Column to be resized.
new_length  New number of elements in column.
Returns:
0 on success. Currently this function always succeeds.
Reallocate a column to a new number of elements. The contents of the column data buffer will be unchanged up to the lesser of the new and old sizes. This is valid as well for the null flags buffer (if present). The pointer to data may change (therefore pointers previously retrieved by calling cpl_column_get_data_int(), cpl_column_get_data_string(), etc. should be discarded). In case of failure, the old data buffer and the old null flags buffer are left intact.

cpl_error_code cpl_column_set cpl_column *    column,
int    row,
double    value
 

Write a value to a numerical column element.

Parameters:
column  Column to be accessed.
row  Position where to write value.
value  Value to write.
Returns:
0 on success. A CPL_ERROR_INVALID_TYPE is returned if the accessed column is not of numerical type.
Write a value to a numerical column element. The value is cast to the accessed column type. The written value is automatically marked as valid. To set a column value to NULL use cpl_column_set_null() instead. Column elements are counted starting from zero.

cpl_error_code cpl_column_set_data_null cpl_column *    column,
cpl_column_flag *    nulls,
int    nullcount
 

Plug a new null buffer into a numerical column.

Parameters:
column  Column to access.
nulls  Array of null flags.
nullcount  Total number of nulls.
Returns:
0 on success. If the column type is string, a null column is not allowed, and an attempt to plug it in will cause a CPL_ERROR_INVALID_TYPE to be returned. A CPL_ERROR_INCOMPATIBLE_INPUT is returned if an impossible nullcount value is passed.
This function is used to assign a new set of null flags to a column. If a null flag buffer already exists, this is deallocated. If nullcount is either 0 or equal to the column length, the passed null flag buffer is ignored, but the internal buffer is deallocated. If the total number of nulls is a negative number, it will be evaluated internally: If a null flag buffer was not passed in this case, the total number of NULLs is assumed to be zero. Use at your own risk: direct manipulation of column data rules out any check performed by the column object interface, and may introduce inconsistencies between the column information maintained internally and the actual column data.

cpl_error_code cpl_column_set_double cpl_column *    column,
int    row,
double    value
 

Write a value to a double column element.

Parameters:
column  Column to be accessed.
row  Position where to write value.
value  Value to write.
Returns:
0 on success. A CPL_ERROR_TYPE_MISMATCH is returned if the accessed column is not of double type.
Write a value to a double column element. Internal conversion is not supported (if column is not double, this is an error). The written value is automatically marked as valid. To set a column value to NULL use cpl_column_set_null() instead. Column elements are counted starting from zero.

cpl_error_code cpl_column_set_float cpl_column *    column,
int    row,
float    value
 

Write a value to a float column element.

Parameters:
column  Column to be accessed.
row  Position where to write value.
value  Value to write.
Returns:
0 on success. A CPL_ERROR_TYPE_MISMATCH is returned if the accessed column is not of float type.
Write a value to a float column element. Internal conversion is not supported (if column is not float, this is an error). The written value is automatically marked as valid. To set a column value to NULL use cpl_column_set_null() instead. Column elements are counted starting from zero.

cpl_error_code cpl_column_set_format cpl_column *    column,
const char *    format
 

Give a new format to a column.

Parameters:
column  Column to access.
format  New column format.
Returns:
0 on success. Currently this function always succeeds.
The input format is duplicated before being used as the column format. If a NULL format is given, "s" will be used if the column is of type string, "g" if the column is of type float or double, and "d" if it is of type integer. The format string associated to a column has no effect on any operation performed on columns, and it is used just while printing a column. The given format string must conform to the legal standard C formats.

cpl_error_code cpl_column_set_int cpl_column *    column,
int    row,
int    value
 

Write a value to an integer column element.

Parameters:
column  Column to be accessed.
row  Position where to write value.
value  Value to write.
Returns:
0 on success. A CPL_ERROR_TYPE_MISMATCH is returned if the accessed column is not of integer type.
Write a value to an integer column element. Internal conversion is not supported (if column is not integer, this is an error). The written value is automatically marked as valid. To set a column value to NULL use cpl_column_set_null() instead. Column elements are counted starting from zero.

cpl_error_code cpl_column_set_name cpl_column *    column,
const char *    name
 

Give a new name to a column.

Parameters:
column  Column to be named.
name  New column name.
Returns:
0 on success. Currently this function always succeeds.
The input name is duplicated before being used as the column name. If the new name is a NULL the column will be nameless.

cpl_error_code cpl_column_set_null cpl_column *    column,
int    row
 

Set a column element to NULL;.

Parameters:
column  Column to be accessed.
row  Position where to write a NULL.
Returns:
0 on success. Currently this function always succeeds.
In the case of a string column, the string is set free and its pointer is set to NULL; for other data types, the corresponding element of the null flags buffer is flagged. Column elements are counted starting from zero.

cpl_error_code cpl_column_set_string cpl_column *    column,
int    row,
const char *    string
 

Write a character string to a string column element.

Parameters:
column  Column to be accessed.
row  Position where to write character string.
string  Character string to write.
Returns:
0 on success. A CPL_ERROR_TYPE_MISMATCH is returned if the accessed column is not of string type.
Copy a character string to a string column element. Internal conversion is not supported (if column is not a string column, this is an error). The written value can also be a NULL. Note that the character string is copyed, therefore the original can be modified without affecting the column content. To "plug" a character string directly into a column element, use the function cpl_column_get_data_string(). Column elements are counted starting from zero.

cpl_error_code cpl_column_set_unit cpl_column *    column,
const char *    unit
 

Give a new unit to a column.

Parameters:
column  Column to access.
unit  New column unit.
Returns:
0 on success. Currently this function always succeeds.
The input unit is duplicated before being used as the column unit. If the new unit is a NULL the column will be unitless. The unit string associated to a column has no effect on any operation performed on columns, and it must be considered just an optional description of the content of a column.

cpl_error_code cpl_column_shift cpl_column *    column,
int    shift
 

Shift numeric column elements.

Parameters:
column  Input column.
shift  Shift column values by so many elements.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned. If the specified shift is in module greater than the column length, a CPL_ERROR_ILLEGAL_INPUT is returned.
All column elements, and the NULL flags if present, are shifted by the specified amount. If shift is positive, all elements will be moved toward the bottom of the column, otherwise toward its top. The column elements that are left undefined at either end of the column are padded with NULLs.

Note:
This function is applicable just to numeric columns.

cpl_error_code cpl_column_subtract cpl_column *    to_column,
cpl_column *    from_column
 

Subtract two numeric columns.

Parameters:
to_column  Target column.
from_column  Column to subtract from target column.
Returns:
0 on success. If the input columns do not have the same length, a CPL_ERROR_INCOMPATIBLE_INPUT is returned. If either or both column is of type string, a CPL_ERROR_INVALID_TYPE is returned.
The result of the subtraction is stored in the target colum. The two columns to subtract must have the same length. Their types may differ, and in that case the operation would be performed according to the C upcasting rules, with a final cast of the result to the target column type. NULL flags are also upgraded: if either or both members of the subtraction are NULLs, the result will be a NULL too. Underflows and overflows are ignored.

cpl_error_code cpl_column_subtract_constant cpl_column *    column,
double    value
 

Subtract a constant value from a numerical column.

Parameters:
column  Target column.
value  Value to subtract.
Returns:
0 on success. If the accessed column is not numerical, a CPL_ERROR_INVALID_TYPE is returned.
The operation is always performed in double precision, with a final cast of the result to the target column type. NULL flags are not modified by this operation.


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