Arrays


Functions

cpl_array * cpl_array_new (int length, cpl_type type)
 Create a new array of given type.
cpl_array * cpl_array_wrap_int (int *data, int length)
 Create a new integer 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_double (double *data, int length)
 Create a new double array from existing data.
cpl_array * cpl_array_wrap_string (char **data, int length)
 Create a new character string array from existing data.
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_int (cpl_array *array, const int *data)
 Copy existing data to an integer 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_double (cpl_array *array, const double *data)
 Copy existing data to a double array.
cpl_error_code cpl_array_copy_data_string (cpl_array *array, const char **data)
 Copy existing data to a string array.
void cpl_array_delete (cpl_array *array)
 Delete an array.
void * cpl_array_unwrap (cpl_array *array)
 Delete an array, without losing the data buffer.
int cpl_array_get_size (const cpl_array *array)
 Get the length of an 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.
int cpl_array_count_invalid (const cpl_array *array)
 Count number of invalid elements in an array.
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.
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.
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.
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 (const cpl_array *array, int indx, int *null)
 Read a value from a numerical array.
int cpl_array_get_int (const cpl_array *array, int indx, int *null)
 Read a value from an integer array.
float cpl_array_get_float (const cpl_array *array, int indx, int *null)
 Read a value from a float array.
double cpl_array_get_double (const cpl_array *array, int indx, int *null)
 Read a value from a double array.
const char * cpl_array_get_string (const cpl_array *array, int indx)
 Read a value from a string array.
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_int (cpl_array *array, int indx, int value)
 Write a value to an integer 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_double (cpl_array *array, int indx, double value)
 Write a value to a double array element.
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_set_invalid (cpl_array *array, int indx)
 Invalidate an array element.
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_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_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_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_string (cpl_array *array, int start, int count, const char *value)
 Write a string to a string array segment.
cpl_error_code cpl_array_fill_window_invalid (cpl_array *array, int start, int count)
 Set an array segment to NULL.
cpl_array * cpl_array_duplicate (const cpl_array *array)
 Make a copy of an array.

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

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.

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

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 Thu Nov 8 15:27:57 2007 for Common Pipeline Library Reference Manual by  doxygen 1.5.1