Arrays


Functions

cpl_error_code cpl_array_abs (cpl_array *array)
 Compute the absolute value of array elements.
cpl_error_code cpl_array_add (cpl_array *to_array, const cpl_array *from_array)
 Add the values of two numeric arrays.
cpl_error_code cpl_array_add_scalar (cpl_array *array, double value)
 Add a constant value to a numerical array.
cpl_error_code cpl_array_copy_data (cpl_array *array, const double *data)
 Copy buffer of numerical data to a numerical array.
cpl_error_code cpl_array_copy_data_double (cpl_array *array, const double *data)
 Copy existing data to a double array.
cpl_error_code cpl_array_copy_data_float (cpl_array *array, const float *data)
 Copy existing data to a float array.
cpl_error_code cpl_array_copy_data_int (cpl_array *array, const int *data)
 Copy existing data to an integer array.
cpl_error_code cpl_array_copy_data_string (cpl_array *array, const char **data)
 Copy existing data to a string array.
int cpl_array_count_invalid (const cpl_array *array)
 Count number of invalid elements in an array.
void cpl_array_delete (cpl_array *array)
 Delete an array.
cpl_error_code cpl_array_divide (cpl_array *to_array, const cpl_array *from_array)
 Divide the values of two numeric arrays.
cpl_error_code cpl_array_divide_scalar (cpl_array *array, double value)
 Divide a numerical array by a constant value.
cpl_array * cpl_array_duplicate (const cpl_array *array)
 Make a copy of an array.
cpl_error_code cpl_array_erase_window (cpl_array *array, int start, int count)
 Delete a segment of an array.
cpl_error_code cpl_array_exponential (cpl_array *array, double base)
 Compute the exponential of array elements.
cpl_array * cpl_array_extract (const cpl_array *array, int start, int count)
 Create an array from a section of another array.
cpl_error_code cpl_array_fill_window (cpl_array *array, int start, int count, double value)
 Write the same value within a numerical array segment.
cpl_error_code cpl_array_fill_window_double (cpl_array *array, int start, int count, double value)
 Write the same value within a double array segment.
cpl_error_code cpl_array_fill_window_float (cpl_array *array, int start, int count, float value)
 Write the same value within a float array segment.
cpl_error_code cpl_array_fill_window_int (cpl_array *array, int start, int count, int value)
 Write the same value within an integer array segment.
cpl_error_code cpl_array_fill_window_invalid (cpl_array *array, int start, int count)
 Set an array segment to NULL.
cpl_error_code cpl_array_fill_window_string (cpl_array *array, int start, int count, const char *value)
 Write a string to a string array segment.
double cpl_array_get (const cpl_array *array, int indx, int *null)
 Read a value from a numerical array.
double * cpl_array_get_data_double (cpl_array *array)
 Get a pointer to double array data.
const double * cpl_array_get_data_double_const (const cpl_array *array)
 Get a pointer to constant double array data.
float * cpl_array_get_data_float (cpl_array *array)
 Get a pointer to float array data.
const float * cpl_array_get_data_float_const (const cpl_array *array)
 Get a pointer to constant float array data.
int * cpl_array_get_data_int (cpl_array *array)
 Get a pointer to integer array data.
const int * cpl_array_get_data_int_const (const cpl_array *array)
 Get a pointer to constant integer array data.
char ** cpl_array_get_data_string (cpl_array *array)
 Get a pointer to string array data.
const char ** cpl_array_get_data_string_const (const cpl_array *array)
 Get a pointer to constant string array data.
double cpl_array_get_double (const cpl_array *array, int indx, int *null)
 Read a value from a double array.
float cpl_array_get_float (const cpl_array *array, int indx, int *null)
 Read a value from a float array.
int cpl_array_get_int (const cpl_array *array, int indx, int *null)
 Read a value from an integer array.
double cpl_array_get_max (const cpl_array *array)
 Get maximum value in a numerical array.
cpl_error_code cpl_array_get_maxpos (const cpl_array *array, int *indx)
 Get position of maximum in a numerical array.
double cpl_array_get_mean (const cpl_array *array)
 Compute the mean value of a numeric array.
double cpl_array_get_median (const cpl_array *array)
 Compute the median of a numeric array.
double cpl_array_get_min (const cpl_array *array)
 Get minimum value in a numerical array.
cpl_error_code cpl_array_get_minpos (const cpl_array *array, int *indx)
 Get position of minimum in a numerical array.
int cpl_array_get_size (const cpl_array *array)
 Get the length of an array.
double cpl_array_get_stdev (const cpl_array *array)
 Compute the standard deviation of a numeric array.
const char * cpl_array_get_string (const cpl_array *array, int indx)
 Read a value from a string array.
cpl_type cpl_array_get_type (const cpl_array *array)
 Get the type of an array.
int cpl_array_has_invalid (const cpl_array *array)
 Check if an array contains at least one invalid element.
int cpl_array_has_valid (const cpl_array *array)
 Check if an array contains at least one valid value.
cpl_error_code cpl_array_insert (cpl_array *target_array, const cpl_array *insert_array, int start)
 Merge two arrays.
cpl_error_code cpl_array_insert_window (cpl_array *array, int start, int count)
 Insert a segment of new elements into array.
cpl_error_code cpl_array_logarithm (cpl_array *array, double base)
 Compute the logarithm of array elements.
cpl_error_code cpl_array_multiply (cpl_array *to_array, const cpl_array *from_array)
 Multiply the values of two numeric arrays.
cpl_error_code cpl_array_multiply_scalar (cpl_array *array, double value)
 Multiply a numerical array by a constant value.
cpl_array * cpl_array_new (int length, cpl_type type)
 Create a new array of given type.
cpl_error_code cpl_array_power (cpl_array *array, double exponent)
 Compute the power of array elements.
cpl_error_code cpl_array_set (cpl_array *array, int indx, double value)
 Write a value to a numerical array element.
cpl_error_code cpl_array_set_double (cpl_array *array, int indx, double value)
 Write a value to a double array element.
cpl_error_code cpl_array_set_float (cpl_array *array, int indx, float value)
 Write a value to a float array element.
cpl_error_code cpl_array_set_int (cpl_array *array, int indx, int value)
 Write a value to an integer array element.
cpl_error_code cpl_array_set_invalid (cpl_array *array, int indx)
 Invalidate an array element.
cpl_error_code cpl_array_set_size (cpl_array *array, int new_length)
 Resize an array.
cpl_error_code cpl_array_set_string (cpl_array *array, int indx, const char *string)
 Write a character string to a string array element.
cpl_error_code cpl_array_subtract (cpl_array *to_array, const cpl_array *from_array)
 Subtract the values of two numeric arrays.
cpl_error_code cpl_array_subtract_scalar (cpl_array *array, double value)
 Subtract a constant value from a numerical array.
void * cpl_array_unwrap (cpl_array *array)
 Delete an array, without losing the data buffer.
cpl_array * cpl_array_wrap_double (double *data, int length)
 Create a new double array from existing data.
cpl_array * cpl_array_wrap_float (float *data, int length)
 Create a new float array from existing data.
cpl_array * cpl_array_wrap_int (int *data, int length)
 Create a new integer array from existing data.
cpl_array * cpl_array_wrap_string (char **data, int length)
 Create a new character string array from existing data.

Detailed Description

This module provides functions to create, destroy and use a cpl_array.

Synopsis:
   #include <cpl_array.h>

Function Documentation

cpl_error_code cpl_array_abs ( cpl_array *  array  ) 

Compute the absolute value of array elements.

Parameters:
array Pointer to array.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array is NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.

Each array element is replaced by its absolute value. Invalid elements are not modified by this operation.

cpl_error_code cpl_array_add ( cpl_array *  to_array,
const cpl_array *  from_array 
)

Add the values of two numeric arrays.

Parameters:
to_array Target array.
from_array Source array.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any input array is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The input arrays have different sizes.
CPL_ERROR_INVALID_TYPE Any specified array is not numerical.

The arrays are summed element by element, and the result of the sum is stored in the target array. The arrays' 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 array type. Invalid elements are propagated consistently: if either or both members of the sum are invalid, the result will be invalid too. Underflows and overflows are ignored.

cpl_error_code cpl_array_add_scalar ( cpl_array *  array,
double  value 
)

Add a constant value to a numerical array.

Parameters:
array Target array
value Value to add.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_INVALID_TYPE The input array is not numerical.

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

cpl_error_code cpl_array_copy_data ( cpl_array *  array,
const double *  data 
)

Copy buffer of numerical data to a numerical array.

Parameters:
array Existing array.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If the array is not numerical, a CPL_ERROR_INVALID_TYPE is returned. At any NULL input pointer a CPL_ERROR_NULL_INPUT would be returned.
The input data are copied into the specified array. If the type of the accessed array is not CPL_TYPE_DOUBLE, the data values will be truncated according to C casting rules. The size of the input data buffer is not checked in any way, and the values are all considered valid: invalid values should be marked using the functions cpl_array_set_invalid(). If N is the length of the array, the first N values of the input data buffer would be copied to the column buffer. If the array had length zero, no values would be copied.

cpl_error_code cpl_array_copy_data_double ( cpl_array *  array,
const double *  data 
)

Copy existing data to a double array.

Parameters:
array Existing array.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If the input array is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is returned. At any NULL input pointer a CPL_ERROR_NULL_INPUT would be returned.
See documentation of function cpl_array_copy_data_int().

cpl_error_code cpl_array_copy_data_float ( cpl_array *  array,
const float *  data 
)

Copy existing data to a float array.

Parameters:
array Existing array.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If the input array is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is returned. At any NULL input pointer a CPL_ERROR_NULL_INPUT would be returned.
See documentation of function cpl_array_copy_data_int().

cpl_error_code cpl_array_copy_data_int ( cpl_array *  array,
const int *  data 
)

Copy existing data to an integer array.

Parameters:
array Existing array.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If the input array is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is returned. At any NULL input pointer a CPL_ERROR_NULL_INPUT would be returned.
The input data are copied into the specified array. The size of the input data buffer is not checked in any way, and the data values are all considered valid: invalid values should be marked using the functions cpl_array_set_invalid(). If N is the length of the array, the first N values of the input data buffer would be copied to the array buffer. If the array had length zero, no values would be copied.

cpl_error_code cpl_array_copy_data_string ( cpl_array *  array,
const char **  data 
)

Copy existing data to a string array.

Parameters:
array Existing array.
data Existing data buffer.
Returns:
CPL_ERROR_NONE on success. If the input array is not of type CPL_TYPE_STRING, a CPL_ERROR_TYPE_MISMATCH is returned. At any NULL input pointer a CPL_ERROR_NULL_INPUT would be returned.
See documentation of function cpl_array_copy_data_int().

The input data are copied into the specified array. The size of the input buffer is not checked in any way. The strings pointed by the input buffer are all duplicated, while the strings contained in the array are released before being overwritten.

int cpl_array_count_invalid ( const cpl_array *  array  ) 

Count number of invalid elements in an array.

Parameters:
array Array to inquire.
Returns:
Number of invalid elements in an array. -1 is always returned in case of error.
Count number of invalid elements in an array. If the array itself is a NULL pointer, an error CPL_ERROR_NULL_INPUT is set.

void cpl_array_delete ( cpl_array *  array  ) 

Delete an array.

Parameters:
array Array to be deleted.
Returns:
Nothing.
This function deletes an array. If the input array is NULL, nothing is done, and no error is set.

cpl_error_code cpl_array_divide ( cpl_array *  to_array,
const cpl_array *  from_array 
)

Divide the values of two numeric arrays.

Parameters:
to_array Target array.
from_array Source array.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any input array is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The input arrays have different sizes.
CPL_ERROR_INVALID_TYPE Any specified array is not numerical.

The arrays are divided element by element, and the result is stored in the target array. See the documentation of the function cpl_array_add() for further details.

cpl_error_code cpl_array_divide_scalar ( cpl_array *  array,
double  value 
)

Divide a numerical array by a constant value.

Parameters:
array Target array
value Divisor.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_INVALID_TYPE The input array is not numerical.
CPL_ERROR_DIVISION_BY_ZERO The input value is zero.

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

cpl_array* cpl_array_duplicate ( const cpl_array *  array  ) 

Make a copy of an array.

Parameters:
array Array to be duplicated.
Returns:
Pointer to the new array, or NULL in case of error.
If the input array is a NULL pointer, a CPL_ERROR_NULL_INPUT is returned. Copy is "in depth": in the case of a string array, also the string elements are duplicated.

cpl_error_code cpl_array_erase_window ( cpl_array *  array,
int  start,
int  count 
)

Delete a segment of an array.

Parameters:
array Input array
start First element to delete.
count Number of elements to delete.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT array is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input array has length zero, or start is outside the table range.
CPL_ERROR_ILLEGAL_INPUT count is negative.

A portion of the array data is physically removed. The pointers to data may change, therefore pointers previously retrieved by calling cpl_array_get_data_int(), cpl_array_get_data_string(), etc., should be discarded. The specified segment can extend beyond the end of the array, and in that case elements will be removed up to the end of the array.

cpl_error_code cpl_array_exponential ( cpl_array *  array,
double  base 
)

Compute the exponential of array elements.

Parameters:
array Pointer to array.
base Exponential base.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array is NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.
CPL_ERROR_ILLEGAL_INPUT The input base is not positive.

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

cpl_array* cpl_array_extract ( const cpl_array *  array,
int  start,
int  count 
)

Create an array from a section of another array.

Parameters:
table Input array
start First element to be copied to new array.
count Number of elements to be copied.
Returns:
Pointer to the new array, or NULL in case or error.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE The input array has zero length, or start is outside the array boundaries.
CPL_ERROR_ILLEGAL_INPUT count is negative.

A number of consecutive elements are copied from an input array to a newly created array. If the sum of start and count goes beyond the end of the input array, elements are copied up to the end.

cpl_error_code cpl_array_fill_window ( cpl_array *  array,
int  start,
int  count,
double  value 
)

Write the same value within a numerical array segment.

Parameters:
array Array to be accessed.
start Position where to begin write value.
count Number of values to write.
value Value to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of numerical type, a CPL_ERROR_INVALID_TYPE is returned. If start is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length zero, the CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned.
Write the same value to a numerical array segment. The value is cast to the accessed array type. The written values are automatically flagged as valid. To invalidate an array interval use cpl_array_fill_window_invalid().

cpl_error_code cpl_array_fill_window_double ( cpl_array *  array,
int  start,
int  count,
double  value 
)

Write the same value within a double array segment.

Parameters:
array Array to be accessed.
start Position where to begin write value.
count Number of values to write.
value Value to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is returned. If start is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length zero, the error CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned. If count is negative, a CPL_ERROR_ILLEGAL_INPUT is returned.
Write the same value to a double array segment. The written values are automatically flagged as valid. To invalidate an array interval use cpl_array_fill_window_invalid(). The count argument can go beyond the array end, and in that case the specified value will be written just up to the end of the array. If count is zero, the array is not modified and no error is set.

cpl_error_code cpl_array_fill_window_float ( cpl_array *  array,
int  start,
int  count,
float  value 
)

Write the same value within a float array segment.

Parameters:
array Array to be accessed.
start Position where to begin write value.
count Number of values to write.
value Value to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is returned. If start is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length zero, the error CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned. If count is negative, a CPL_ERROR_ILLEGAL_INPUT is returned.
Write the same value to a float array segment. The written values are automatically flagged as valid. To invalidate an array interval use cpl_array_fill_window_invalid(). The count argument can go beyond the array end, and in that case the specified value will be written just up to the end of the array. If count is zero, the array is not modified and no error is set.

cpl_error_code cpl_array_fill_window_int ( cpl_array *  array,
int  start,
int  count,
int  value 
)

Write the same value within an integer array segment.

Parameters:
array Array to be accessed.
start Position where to begin write value.
count Number of values to write.
value Value to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is returned. If start is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length zero, the error CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned. If count is negative, a CPL_ERROR_ILLEGAL_INPUT is returned.
Write the same value to an integer array segment. The written values are automatically flagged as valid. To invalidate an array interval use cpl_array_fill_window_invalid(). The count argument can go beyond the array end, and in that case the specified value will be written just up to the end of the array. If count is zero, the array is not modified and no error is set.

cpl_error_code cpl_array_fill_window_invalid ( cpl_array *  array,
int  start,
int  count 
)

Set an array segment to NULL.

Parameters:
array Array to be accessed.
start Position where to start writing NULLs.
count Number of column elements to set to NULL.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If start is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length zero, the error CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned. If count is negative, a CPL_ERROR_ILLEGAL_INPUT is returned.
Invalidate values contained in an array segment. The count argument can go beyond the array end, and in that case the values will be invalidated up to the end of the array. If count is zero, the array is not modified and no error is set. In the case of a string array, the invalidated strings are set free and their pointers are set to NULL; for other data types, the corresponding elements are flagged as invalid.

cpl_error_code cpl_array_fill_window_string ( cpl_array *  array,
int  start,
int  count,
const char *  value 
)

Write a string to a string array segment.

Parameters:
array Array to be accessed.
start Position where to begin write value.
count Number of values to write.
value Value to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is returned. If start is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length zero, the error CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned. If count is negative, a CPL_ERROR_ILLEGAL_INPUT is returned.
Copy the same string to a string array segment. If the input string is not a NULL pointer, it is duplicated for each accessed array element. If the input string is NULL, this call is equivalent to cpl_array_fill_window_invalid(). The count argument can go beyond the array end, and in that case the specified value will be copied just up to the end of the array. If count is zero, the array is not modified and no error is set.

double cpl_array_get ( const cpl_array *  array,
int  indx,
int *  null 
)

Read a value from a numerical array.

Parameters:
array Array to be accessed.
indx Position of element to be read.
null Flag indicating null values, or error condition.
Returns:
Value read. In case of an invalid array element, or in case of error, 0.0 is returned.
Read a value from a numerical array. A CPL_ERROR_NULL_INPUT is set in case array is a NULL pointer. A CPL_ERROR_INVALID_TYPE is set in case a non-numerical array is accessed. CPL_ERROR_ACCESS_OUT_OF_RANGE is set if the indx is outside the array range. Indexes are counted starting from 0. If the input array has length zero, CPL_ERROR_ACCESS_OUT_OF_RANGE is always set. The null flag is used to indicate whether the accessed array element is valid (0) or invalid (1). The null flag also signals an error condition (-1). The null argument can be left to NULL.

double* cpl_array_get_data_double ( cpl_array *  array  ) 

Get a pointer to double array data.

Parameters:
array Array to get the data from.
Returns:
Pointer to double array data. If array contains no data (zero length), a NULL is returned. If array is a NULL, a NULL is returned, and an error is set.
If the array is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is set.

See documentation of function cpl_array_get_data_int().

const double* cpl_array_get_data_double_const ( const cpl_array *  array  ) 

Get a pointer to constant double array data.

Parameters:
array Constant array to get the data from.
Returns:
Pointer to constant double array data. If array contains no data (zero length), a NULL is returned. If array is a NULL, a NULL is returned, and an error is set.
If the array is not of type CPL_TYPE_DOUBLE, a CPL_ERROR_TYPE_MISMATCH is set.

See documentation of function cpl_array_get_data_int_const().

float* cpl_array_get_data_float ( cpl_array *  array  ) 

Get a pointer to float array data.

Parameters:
array Array to get the data from.
Returns:
Pointer to float array data. If array contains no data (zero length), a NULL is returned. If array is a NULL, a NULL is returned, and an error is set.
If the array is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is set.

See documentation of function cpl_array_get_data_int().

const float* cpl_array_get_data_float_const ( const cpl_array *  array  ) 

Get a pointer to constant float array data.

Parameters:
array Constant array to get the data from.
Returns:
Pointer to constant float array data. If array contains no data (zero length), a NULL is returned. If array is a NULL, a NULL is returned, and an error is set.
If the array is not of type CPL_TYPE_FLOAT, a CPL_ERROR_TYPE_MISMATCH is set.

See documentation of function cpl_array_get_data_int_const().

int* cpl_array_get_data_int ( cpl_array *  array  ) 

Get a pointer to integer array data.

Parameters:
array Array to get the data from.
Returns:
Pointer to integer array data. If array contains no data (zero length), a NULL is returned. If array is a NULL, a NULL is returned, and an error is set.
If the array is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is set.

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

const int* cpl_array_get_data_int_const ( const cpl_array *  array  ) 

Get a pointer to constant integer array data.

Parameters:
array Constant array to get the data from.
Returns:
Pointer to constant integer array data. If array contains no data (zero length), a NULL is returned. If array is a NULL, a NULL is returned, and an error is set.
If the array is not of type CPL_TYPE_INT, a CPL_ERROR_TYPE_MISMATCH is set.

char** cpl_array_get_data_string ( cpl_array *  array  ) 

Get a pointer to string array data.

Parameters:
array Array to get the data from.
Returns:
Pointer to string array data. If array contains no data (zero length), a NULL is returned. If array is a NULL, a NULL is returned, and an error is set.
If the array is not of type CPL_TYPE_STRING, a CPL_ERROR_TYPE_MISMATCH is set.

See documentation of function cpl_array_get_data_int().

const char** cpl_array_get_data_string_const ( const cpl_array *  array  ) 

Get a pointer to constant string array data.

Parameters:
array Constant array to get the data from.
Returns:
Pointer to constant string array data. If array contains no data (zero length), a NULL is returned. If array is a NULL, a NULL is returned, and an error is set.
If the array is not of type CPL_TYPE_STRING, a CPL_ERROR_TYPE_MISMATCH is set.

See documentation of function cpl_array_get_data_int().

double cpl_array_get_double ( const cpl_array *  array,
int  indx,
int *  null 
)

Read a value from a double array.

Parameters:
array Array to be accessed.
indx Position of element to be read.
null Flag indicating null values, or error condition.
Returns:
Array value read. In case of an invalid array element, or in case of error, 0.0 is returned.
Read a value from an array of type CPL_TYPE_DOUBLE. See the documentation of the function cpl_array_get_int().

float cpl_array_get_float ( const cpl_array *  array,
int  indx,
int *  null 
)

Read a value from a float array.

Parameters:
array Array to be accessed.
indx Position of element to be read.
null Flag indicating null values, or error condition.
Returns:
Array value read. In case of an invalid array element, or in case of error, 0.0 is returned.
Read a value from an array of type CPL_TYPE_FLOAT. See the documentation of the function cpl_array_get_int().

int cpl_array_get_int ( const cpl_array *  array,
int  indx,
int *  null 
)

Read a value from an integer array.

Parameters:
array Array to be accessed.
indx Position of element to be read.
null Flag indicating null values, or error condition.
Returns:
Integer value read. In case of an invalid array element, or in case of error, 0 is returned.
Read a value from an array of type CPL_TYPE_INT. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is set. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is set. If indx is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is set. Indexes are counted starting from 0. If the input array has length zero, the CPL_ERROR_ACCESS_OUT_OF_RANGE is always set. If the null flag is a valid pointer, it is used to indicate whether the accessed array element is valid (0) or invalid (1). The null flag also signals an error condition (-1).

double cpl_array_get_max ( const cpl_array *  array  ) 

Get maximum value in a numerical array.

Parameters:
array Input array.
Returns:
Maximum value. In case of error, this is set to 0.0.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.
CPL_ERROR_DATA_NOT_FOUND The specified array has either size zero, or all its elements are invalid.

Array elements marked as invalid are excluded from the search. The array must contain at least one valid value. Arrays of strings are not allowed.

cpl_error_code cpl_array_get_maxpos ( const cpl_array *  array,
int *  indx 
)

Get position of maximum in a numerical array.

Parameters:
array Pointer to array.
indx Returned position of maximum value.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array or indx is NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.
CPL_ERROR_DATA_NOT_FOUND The specified array has either size zero, or all its elements are invalid.

Array values marked as invalid are excluded from the search. The indx argument will be assigned the position of the maximum value. Indexes are counted starting from 0. If more than one array element correspond to the max value, the position with the lowest indx is returned. In case of error, indx is set to zero. Arrays of strings are not allowed.

double cpl_array_get_mean ( const cpl_array *  array  ) 

Compute the mean value of a numeric array.

Parameters:
array Input array.
Returns:
Mean value. In case of error, this is set to 0.0.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.
CPL_ERROR_DATA_NOT_FOUND The specified array has either size zero, or all its elements are invalid.

Array elements marked as invalid are excluded from the computation. The array must contain at least one valid value. Arrays of strings are not allowed.

double cpl_array_get_median ( const cpl_array *  array  ) 

Compute the median of a numeric array.

Parameters:
array Input array.
Returns:
Median. In case of error, this is set to 0.0.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.
CPL_ERROR_DATA_NOT_FOUND The specified array has either size zero, or all its elements are invalid.

Array elements marked as invalid are excluded from the computation. The array must contain at least one valid value. Arrays of strings are not allowed.

double cpl_array_get_min ( const cpl_array *  array  ) 

Get minimum value in a numerical array.

Parameters:
array Input array.
Returns:
Minimum value. In case of error, this is set to 0.0.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.
CPL_ERROR_DATA_NOT_FOUND The specified array has either size zero, or all its elements are invalid.

Array elements marked as invalid are excluded from the search. The array must contain at least one valid value. Arrays of strings are not allowed.

cpl_error_code cpl_array_get_minpos ( const cpl_array *  array,
int *  indx 
)

Get position of minimum in a numerical array.

Parameters:
array Pointer to array.
indx Returned position of minimum value.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array or indx is NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.
CPL_ERROR_DATA_NOT_FOUND The specified array has either size zero, or all its elements are invalid.

Array values marked as invalid are excluded from the search. The indx argument will be assigned the position of the minimum value. Indexes are counted starting from 0. If more than one array element correspond to the min value, the position with the lowest indx is returned. In case of error, indx is set to zero. Arrays of strings are not allowed.

int cpl_array_get_size ( const cpl_array *  array  ) 

Get the length of an array.

Parameters:
array Input array.
Returns:
Length of array, or zero. The latter case can occur either with an array having zero length, or if a NULL array is passed to the function, but in the latter case a CPL_ERROR_NULL_INPUT is set.
If the array is NULL, zero is returned.

double cpl_array_get_stdev ( const cpl_array *  array  ) 

Compute the standard deviation of a numeric array.

Parameters:
array Input array.
Returns:
Standard deviation. In case of error, this is set to 0.0.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.
CPL_ERROR_DATA_NOT_FOUND The specified array has either size zero, or all its elements are invalid.

Array elements marked as invalid are excluded from the computation. The array must contain at least one valid value. Arrays of strings are not allowed.

const char* cpl_array_get_string ( const cpl_array *  array,
int  indx 
)

Read a value from a string array.

Parameters:
array Array to be accessed.
indx Position of element to be read.
Returns:
Character string read. In case of an invalid array element, or in case of error, a NULL pointer is returned.
Read a value from an array of type CPL_TYPE_STRING. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is set. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is set. If indx is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is set. Indexes are counted starting from 0. If the input array has length zero, the CPL_ERROR_ACCESS_OUT_OF_RANGE is always set.

Note:
The returned string is a pointer to an array element, not its copy. Its manipulation will directly affect that array element, while changing that array element using cpl_array_set_string() will turn it into garbage. Therefore, if a real copy of a string array element is required, this function should be called as an argument of the function strdup().

cpl_type cpl_array_get_type ( const cpl_array *  array  ) 

Get the type of an array.

Parameters:
array Input array
Returns:
Type of array, or CPL_TYPE_INVALID if a NULL array is passed to the function.
If the array is NULL, CPL_ERROR_NULL_INPUT is set.

int cpl_array_has_invalid ( const cpl_array *  array  ) 

Check if an array contains at least one invalid element.

Parameters:
array Array to inquire.
Returns:
1 if the array contains at least one invalid element, 0 if not, -1 in case of error.
Check if there are invalid elements in an array. If the input array is a NULL pointer, a CPL_ERROR_NULL_INPUT is set.

int cpl_array_has_valid ( const cpl_array *  array  ) 

Check if an array contains at least one valid value.

Parameters:
array Array to inquire.
Returns:
1 if the array contains at least one valid value, 0 if not -1 in case of error.
Check if there are valid values in an array. If the input array is a NULL pointer, a CPL_ERROR_NULL_INPUT is set.

cpl_error_code cpl_array_insert ( cpl_array *  target_array,
const cpl_array *  insert_array,
int  start 
)

Merge two arrays.

Parameters:
target_array Target array.
insert_array Array to be inserted in the target array.
start Element where to insert the insert array.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any input array is a NULL pointer.
CPL_ERROR_ACCESS_OUT_OF_RANGE start is negative.
CPL_ERROR_TYPE_MISMATCH The input arrays do not have the same type.

The input arrays must have the same type. Data from the insert_array are duplicated and inserted at the specified position of the target_array. If the specified start is not less than the target array length, the second array will be appended to the target array. The pointers to array data in the target array may change, therefore pointers previously retrieved by calling cpl_array_get_data_int(), cpl_array_get_data_string(), etc., should be discarded.

cpl_error_code cpl_array_insert_window ( cpl_array *  array,
int  start,
int  count 
)

Insert a segment of new elements into array.

Parameters:
table Input array
start Element where to insert the segment.
count Length of the segment.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT array 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 (invalid) elements. Setting start to a number greater than the array length is legal, and has the effect of appending extra elements at the end of the array: this is equivalent to expanding the array using cpl_array_set_size(). The input array may also have zero length. The pointers to array data values may change, therefore pointers previously retrieved by calling cpl_array_get_data_int(), cpl_array_get_data_string(), etc., should be discarded.

cpl_error_code cpl_array_logarithm ( cpl_array *  array,
double  base 
)

Compute the logarithm of array elements.

Parameters:
array Pointer to array.
base Logarithm base.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array is NULL pointer.
CPL_ERROR_INVALID_TYPE The specified array is not numerical.
CPL_ERROR_ILLEGAL_INPUT The input base is not positive.

Each array 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 array type. Invalid elements are not modified by this operation, but zero or negative elements are invalidated by this operation.

cpl_error_code cpl_array_multiply ( cpl_array *  to_array,
const cpl_array *  from_array 
)

Multiply the values of two numeric arrays.

Parameters:
to_array Target array.
from_array Source array.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any input array is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The input arrays have different sizes.
CPL_ERROR_INVALID_TYPE Any specified array is not numerical.

The arrays are multiplied element by element, and the result is stored in the target array. See the documentation of the function cpl_array_add() for further details.

cpl_error_code cpl_array_multiply_scalar ( cpl_array *  array,
double  value 
)

Multiply a numerical array by a constant value.

Parameters:
array Target array
value Factor.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_INVALID_TYPE The input array is not numerical.

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

cpl_array* cpl_array_new ( int  length,
cpl_type  type 
)

Create a new array of given type.

Parameters:
length Number of elements in array.
type Type of array
Returns:
Pointer to the new array, or NULL in case of error.
This function allocates memory for an array, its type is assigned, and its number of elements is allocated. Only arrays of types CPL_TYPE_INT, CPL_TYPE_FLOAT, CPL_TYPE_DOUBLE, and CPL_TYPE_STRING, are supported. An error CPL_ERROR_INVALID_TYPE is set in case other types are specified. All array elements are initially flagged as invalid. If a negative length is specified, an error CPL_ERROR_ILLEGAL_INPUT is set. Zero length arrays are allowed.

cpl_error_code cpl_array_power ( cpl_array *  array,
double  exponent 
)

Compute the power of array elements.

Parameters:
array Pointer to array.
exponent Constant exponent.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array is NULL.
CPL_ERROR_INVALID_TYPE The array is not numerical.

Each array element is replaced by its power to the specified exponent. The operation is always performed in double precision, with a final cast of the result to the array type. Invalid elements are not modified by this operation, but elements are invalidated at any illegal operation: if the specified exponent is not negative, all array elements must be not negative, and if the specified exponent is negative, all array elements must be positive; array elements not fulfilling this condition will be invalidated. If the exponent is 0.0, then any (valid) array element would be assigned the value 1.0.

cpl_error_code cpl_array_set ( cpl_array *  array,
int  indx,
double  value 
)

Write a value to a numerical array element.

Parameters:
array Array to be accessed.
indx Position where to write value.
value Value to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of numerical type, a CPL_ERROR_INVALID_TYPE is returned. If indx is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length zero, the CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned.
Write a value to a numerical array element. The value is cast to the accessed array type. The written value is automatically flagged as valid. To invalidate an array value use cpl_array_set_invalid(). Array elements are counted starting from 0.

cpl_error_code cpl_array_set_double ( cpl_array *  array,
int  indx,
double  value 
)

Write a value to a double array element.

Parameters:
array Array to be accessed.
indx Position where to write value.
value Value to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is set. If indx is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length 0, the CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned.
Write a value to a double array element. The written value is automatically flagged as valid. To invalidate an array value use cpl_array_set_invalid(). Array elements are counted starting from 0.

cpl_error_code cpl_array_set_float ( cpl_array *  array,
int  indx,
float  value 
)

Write a value to a float array element.

Parameters:
array Array to be accessed.
indx Position where to write value.
value Value to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is set. If indx is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length 0, the CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned.
Write a value to a float array element. The written value is automatically flagged as valid. To invalidate an array value use cpl_array_set_invalid(). Array elements are counted starting from 0.

cpl_error_code cpl_array_set_int ( cpl_array *  array,
int  indx,
int  value 
)

Write a value to an integer array element.

Parameters:
array Array to be accessed.
indx Position where to write value.
value Value to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is set. If indx is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length 0, the CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned.
Write a value to an integer array element. The written value is automatically flagged as valid. To invalidate an array value use cpl_array_set_invalid(). Array elements are counted starting from 0.

cpl_error_code cpl_array_set_invalid ( cpl_array *  array,
int  indx 
)

Invalidate an array element.

Parameters:
array Array to be accessed
indx Position of element to invalidate
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If indx is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is set. If the input array has length 0, the CPL_ERROR_ACCESS_OUT_OF_RANGE is always set.
In the case of a string array, 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. Array elements are counted starting from zero.

cpl_error_code cpl_array_set_size ( cpl_array *  array,
int  new_length 
)

Resize an array.

Parameters:
array Input array.
new_length New number of elements in array.
Returns:
CPL_ERROR_NONE on success. The new array size must not be negative, or a CPL_ERROR_ILLEGAL_INPUT is returned. The input array pointer should not be NULL, or a CPL_ERROR_NULL_INPUT is returned.
Reallocate an array to a new number of elements. The contents of the array data buffer will be unchanged up to the lesser of the new and old sizes. If the array size is increased, the new array elements are flagged as invalid. The pointer to data may change, therefore pointers previously retrieved by calling cpl_array_get_data_int(), cpl_array_get_data_string(), etc. should be discarded). Resizing to zero is allowed, and would produce a zero-length array. In case of failure, the old data buffer is left intact.

If the array is NULL, zero is returned.

cpl_error_code cpl_array_set_string ( cpl_array *  array,
int  indx,
const char *  string 
)

Write a character string to a string array element.

Parameters:
array Array to be accessed.
indx Position where to write character string.
string Character string to write.
Returns:
CPL_ERROR_NONE on success. If array is a NULL pointer a CPL_ERROR_NULL_INPUT is returned. If the array is not of the expected type, a CPL_ERROR_TYPE_MISMATCH is returned. If indx is outside the array range, a CPL_ERROR_ACCESS_OUT_OF_RANGE is returned. If the input array has length 0, the CPL_ERROR_ACCESS_OUT_OF_RANGE is always returned.
Copy a character string to a string array element. The written value can also be a NULL pointer. Note that the input character string is copied, therefore the original can be modified without affecting the column content. To "plug" a character string directly into an array element, use the function cpl_array_get_data_string(). Array elements are counted starting from zero.

cpl_error_code cpl_array_subtract ( cpl_array *  to_array,
const cpl_array *  from_array 
)

Subtract the values of two numeric arrays.

Parameters:
to_array Target array.
from_array Source array.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Any input array is a NULL pointer.
CPL_ERROR_INCOMPATIBLE_INPUT The input arrays have different sizes.
CPL_ERROR_INVALID_TYPE Any specified array is not numerical.

The arrays are subtracted element by element, and the result is stored in the target array. See the documentation of the function cpl_array_add() for further details.

cpl_error_code cpl_array_subtract_scalar ( cpl_array *  array,
double  value 
)

Subtract a constant value from a numerical array.

Parameters:
array Target array
value Value to subtract.
Returns:
CPL_ERROR_NONE on success.
Errors:
CPL_ERROR_NULL_INPUT Input array is a NULL pointer.
CPL_ERROR_INVALID_TYPE The input array is not numerical.

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

void* cpl_array_unwrap ( cpl_array *  array  ) 

Delete an array, without losing the data buffer.

Parameters:
array Array to be deleted.
Returns:
Pointer to the internal data buffer.
This function deletes an array, but its 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_array_get_data_int(), cpl_array_get_data_float(), etc. If the input array is NULL, nothing is done, and no error is set.

cpl_array* cpl_array_wrap_double ( double *  data,
int  length 
)

Create a new double array from existing data.

Parameters:
data Existing data buffer.
length Number of elements in array.
Returns:
Pointer to the new array, or NULL in case of error.
See documentation of function cpl_array_wrap_int().

cpl_array* cpl_array_wrap_float ( float *  data,
int  length 
)

Create a new float array from existing data.

Parameters:
data Existing data buffer.
length Number of elements in array.
Returns:
Pointer to the new array, or NULL in case of error.
See documentation of function cpl_array_wrap_int().

cpl_array* cpl_array_wrap_int ( int *  data,
int  length 
)

Create a new integer array from existing data.

Parameters:
data Existing data buffer.
length Number of elements in array.
Returns:
Pointer to the new array, or NULL in case of error.
This function creates a new integer array that will encapsulate the given data. Note that the size of the data buffer is not checked in any way, and that the data values are all considered valid: invalid values should be marked using the functions cpl_array_set_invalid() The data array is not copied, so it should never be deallocated: to deallocate it, the function cpl_array_delete() should be called instead. Alternatively, the function cpl_array_unwrap() might be used, and the data array deallocated afterwards. A zero or negative length is illegal, and would cause an error CPL_ERROR_ILLEGAL_INPUT to be set. An input NULL pointer would set an error CPL_ERROR_NULL_INPUT.

Note:
Functions that handle arrays assume that an array data buffer is dinamically allocated: with a statically allocated data buffer any function implying memory handling (cpl_array_set_size(), cpl_array_delete(), etc.) would crash the program. This means that a static data buffer should never be passed to this function if memory handling is planned. In case of a static data buffer, only the cpl_array_unwrap() destructor can be used.

cpl_array* cpl_array_wrap_string ( char **  data,
int  length 
)

Create a new character string array from existing data.

Parameters:
data Existing data buffer.
length Number of elements in array.
Returns:
Pointer to the new array, or NULL in case of error.
See documentation of function cpl_array_wrap_int().


Generated on Wed Mar 18 09:40:12 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7