Loading...
Searching...
No Matches
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 or complex 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_add_scalar_complex (cpl_array *array, double complex value)
| Add a constant complex value to a complex array.
cpl_error_code | cpl_array_arg (cpl_array *array)
| Compute the phase angle value of array elements.
cpl_array * | cpl_array_cast (const cpl_array *array, cpl_type type)
| Cast a numeric array to a new numeric type 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_complex (cpl_array *array, const double complex *data)
| Copy buffer of complex data to a complex array.
cpl_error_code | cpl_array_copy_data_cplsize (cpl_array *array, const cpl_size *data)
| Copy existing data to a cpl_size 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_double_complex (cpl_array *array, const double complex *data)
| Copy existing data to a double complex 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_float_complex (cpl_array *array, const float complex *data)
| Copy existing data to a float complex 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_long (cpl_array *array, const long *data)
| Copy existing data to a long integer array.
cpl_error_code | cpl_array_copy_data_long_long (cpl_array *array, const long long *data)
| Copy existing data to a long long integer array.
cpl_error_code | cpl_array_copy_data_string (cpl_array *array, const char **data)
| Copy existing data to a string array.
cpl_size | 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 or complex arrays.
cpl_error_code | cpl_array_divide_scalar (cpl_array *array, double value)
| Divide a numerical array by a constant value.
cpl_error_code | cpl_array_divide_scalar_complex (cpl_array *array, double complex value)
| Divide a complex array by a constant complex value.
void | cpl_array_dump (const cpl_array *array, cpl_size start, cpl_size count, FILE *stream)
| Print an array.
void | cpl_array_dump_structure (const cpl_array *array, FILE *stream)
| Describe the structure and the contents of an array.
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, cpl_size start, cpl_size 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, cpl_size start, cpl_size count)
| Create an array from a section of another array.
cpl_array * | cpl_array_extract_imag (const cpl_array *array)
| Extract the imaginary value of array elements.
cpl_array * | cpl_array_extract_real (const cpl_array *array)
| Extract the real value of array elements.
cpl_error_code | cpl_array_fill_window (cpl_array *array, cpl_size start, cpl_size count, double value)
| Write the same value within a numerical array segment.
cpl_error_code | cpl_array_fill_window_complex (cpl_array *array, cpl_size start, cpl_size count, double complex value)
| Write the same value within a complex array segment.
cpl_error_code | cpl_array_fill_window_cplsize (cpl_array *array, cpl_size start, cpl_size count, cpl_size value)
| Write the same value within a cpl_size array segment.
cpl_error_code | cpl_array_fill_window_double (cpl_array *array, cpl_size start, cpl_size count, double value)
| Write the same value within a double array segment.
cpl_error_code | cpl_array_fill_window_double_complex (cpl_array *array, cpl_size start, cpl_size count, double complex value)
| Write the same value within a double complex array segment.
cpl_error_code | cpl_array_fill_window_float (cpl_array *array, cpl_size start, cpl_size count, float value)
| Write the same value within a float array segment.
cpl_error_code | cpl_array_fill_window_float_complex (cpl_array *array, cpl_size start, cpl_size count, float complex value)
| Write the same value within a float complex array segment.
cpl_error_code | cpl_array_fill_window_int (cpl_array *array, cpl_size start, cpl_size count, int value)
| Write the same value within an integer array segment.
cpl_error_code | cpl_array_fill_window_invalid (cpl_array *array, cpl_size start, cpl_size count)
| Set an array segment to NULL.
cpl_error_code | cpl_array_fill_window_long (cpl_array *array, cpl_size start, cpl_size count, long value)
| Write the same value within a long integer array segment.
cpl_error_code | cpl_array_fill_window_long_long (cpl_array *array, cpl_size start, cpl_size count, long long value)
| Write the same value within a long long integer array segment.
cpl_error_code | cpl_array_fill_window_string (cpl_array *array, cpl_size start, cpl_size count, const char *value)
| Write a string to a string array segment.
double | cpl_array_get (const cpl_array *array, cpl_size indx, int *null)
| Read a value from a numerical array.
double complex | cpl_array_get_complex (const cpl_array *array, cpl_size indx, int *null)
| Read a value from a complex array.
cpl_size | cpl_array_get_cplsize (const cpl_array *array, cpl_size indx, int *null)
| Read a value from a cpl_size array.
cpl_size * | cpl_array_get_data_cplsize (cpl_array *array)
| Get a pointer to `cpl_size` array data.
const cpl_size * | cpl_array_get_data_cplsize_const (const cpl_array *array)
| Get a pointer to constant `cpl_size` array data.
double * | cpl_array_get_data_double (cpl_array *array)
| Get a pointer to `double` array data.
double complex * | cpl_array_get_data_double_complex (cpl_array *array)
| Get a pointer to `double` complex array data.
const double complex * | cpl_array_get_data_double_complex_const (const cpl_array *array)
| Get a pointer to constant double complex 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.
float complex * | cpl_array_get_data_float_complex (cpl_array *array)
| Get a pointer to `float` complex array data.
const float complex * | cpl_array_get_data_float_complex_const (const cpl_array *array)
| Get a pointer to constant float complex 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.
long * | cpl_array_get_data_long (cpl_array *array)
| Get a pointer to `long` `integer` array data.
const long * | cpl_array_get_data_long_const (const cpl_array *array)
| Get a pointer to constant `long` `integer` array data.
long long * | cpl_array_get_data_long_long (cpl_array *array)
| Get a pointer to `long` `long` `integer` array data.
const long long * | cpl_array_get_data_long_long_const (const cpl_array *array)
| Get a pointer to constant `long` `long` `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, cpl_size indx, int *null)
| Read a value from a double array.
double complex | cpl_array_get_double_complex (const cpl_array *array, cpl_size indx, int *null)
| Read a value from a double complex array.
float | cpl_array_get_float (const cpl_array *array, cpl_size indx, int *null)
| Read a value from a float array.
float complex | cpl_array_get_float_complex (const cpl_array *array, cpl_size indx, int *null)
| Read a value from a float complex array.
int | cpl_array_get_int (const cpl_array *array, cpl_size indx, int *null)
| Read a value from an integer array.
long | cpl_array_get_long (const cpl_array *array, cpl_size indx, int *null)
| Read a value from a long integer array.
long long | cpl_array_get_long_long (const cpl_array *array, cpl_size indx, int *null)
| Read a value from a long long 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, cpl_size *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 complex | cpl_array_get_mean_complex (const cpl_array *array)
| Compute the mean value of a complex 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, cpl_size *indx)
| Get position of minimum in a numerical array.
cpl_size | 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, cpl_size 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, cpl_size start)
| Merge two arrays.
cpl_error_code | cpl_array_insert_window (cpl_array *array, cpl_size start, cpl_size count)
| Insert a segment of new elements into array.
int | cpl_array_is_valid (const cpl_array *array, cpl_size indx)
| Check if an array element is valid.
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 or complex arrays.
cpl_error_code | cpl_array_multiply_scalar (cpl_array *array, double value)
| Multiply a numerical array by a constant value.
cpl_error_code | cpl_array_multiply_scalar_complex (cpl_array *array, double complex value)
| Multiply a complex array by a constant complex value.
cpl_array * | cpl_array_new (cpl_size 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 numerical array elements.
cpl_error_code | cpl_array_power_complex (cpl_array *array, double complex exponent)
| Compute the complex power of complex, numerical array elements.
cpl_error_code | cpl_array_set (cpl_array *array, cpl_size indx, double value)
| Write a value to a numerical array element.
cpl_error_code | cpl_array_set_complex (cpl_array *array, cpl_size indx, double complex value)
| Write a value to a complex array element.
cpl_error_code | cpl_array_set_cplsize (cpl_array *array, cpl_size indx, cpl_size value)
| Write a value to a cpl_size array element.
cpl_error_code | cpl_array_set_double (cpl_array *array, cpl_size indx, double value)
| Write a value to a double array element.
cpl_error_code | cpl_array_set_double_complex (cpl_array *array, cpl_size indx, double complex value)
| Write a value to a double complex array element.
cpl_error_code | cpl_array_set_float (cpl_array *array, cpl_size indx, float value)
| Write a value to a float array element.
cpl_error_code | cpl_array_set_float_complex (cpl_array *array, cpl_size indx, float complex value)
| Write a value to a float complex array element.
cpl_error_code | cpl_array_set_int (cpl_array *array, cpl_size indx, int value)
| Write a value to an integer array element.
cpl_error_code | cpl_array_set_invalid (cpl_array *array, cpl_size indx)
| Invalidate an array element.
cpl_error_code | cpl_array_set_long (cpl_array *array, cpl_size indx, long value)
| Write a value to a long integer array element.
cpl_error_code | cpl_array_set_long_long (cpl_array *array, cpl_size indx, long long value)
| Write a value to a long long integer array element.
cpl_error_code | cpl_array_set_size (cpl_array *array, cpl_size new_length)
| Resize an array.
cpl_error_code | cpl_array_set_string (cpl_array *array, cpl_size 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 or complex arrays.
cpl_error_code | cpl_array_subtract_scalar (cpl_array *array, double value)
| Subtract a constant value from a numerical array.
cpl_error_code | cpl_array_subtract_scalar_complex (cpl_array *array, double complex value)
| Subtract a constant complex value from a complex array.
void * | cpl_array_unwrap (cpl_array *array)
| Delete an array, without losing the data buffer.
cpl_array * | cpl_array_wrap_cplsize (cpl_size *data, cpl_size length)
| Create a new cpl_size array from existing data.
cpl_array * | cpl_array_wrap_double (double *data, cpl_size length)
| Create a new double array from existing data.
cpl_array * | cpl_array_wrap_double_complex (double complex *data, cpl_size length)
| Create a new double complex array from existing data.
cpl_array * | cpl_array_wrap_float (float *data, cpl_size length)
| Create a new float array from existing data.
cpl_array * | cpl_array_wrap_float_complex (float complex *data, cpl_size length)
| Create a new float complex array from existing data.
cpl_array * | cpl_array_wrap_int (int *data, cpl_size length)
| Create a new integer array from existing data.
cpl_array * | cpl_array_wrap_long (long *data, cpl_size length)
| Create a new long integer array from existing data.
cpl_array * | cpl_array_wrap_long_long (long long *data, cpl_size length)
| Create a new long long integer array from existing data.
cpl_array * | cpl_array_wrap_string (char **data, cpl_size 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_array_abs()

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. If the array is complex, its type will be turned to real (CPL_TYPE_FLOAT_COMPLEX will be changed into CPL_TYPE_FLOAT, and CPL_TYPE_DOUBLE_COMPLEX will be changed into CPL_TYPE_DOUBLE), and any pointer retrieved by calling `cpl_array_get_data_float()`, `cpl_array_get_data_double_complex()`, etc., should be discarded.

References cpl_array_get_type(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and CPL_TYPE_COMPLEX.

## cpl_array_add()

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

Add the values of two numeric or complex 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_add_scalar()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_add_scalar_complex()

cpl_error_code cpl_array_add_scalar_complex | ( | cpl_array * | array,
|  | double complex | value )

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

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_arg()

cpl_error_code cpl_array_arg | ( | cpl_array * | array | ) |

Compute the phase angle 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 phase angle value. The phase angle will be in the range of [-pi,pi]. Invalid elements are not modified by this operation. If the array is complex, its type will be turned to real (CPL_TYPE_FLOAT_COMPLEX will be changed into CPL_TYPE_FLOAT, and CPL_TYPE_DOUBLE_COMPLEX will be changed into CPL_TYPE_DOUBLE), and any pointer retrieved by calling `cpl_array_get_data_float()`, `cpl_array_get_data_double_complex()`, etc., should be discarded.

References cpl_array_get_data_double(), cpl_array_get_data_float(), cpl_array_get_size(), cpl_array_get_type(), CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_TYPE_COMPLEX, CPL_TYPE_DOUBLE, and CPL_TYPE_FLOAT.

## cpl_array_cast()

cpl_array * cpl_array_cast | ( | const cpl_array * | array,
|  | cpl_type | type )

Cast a numeric array to a new numeric type array.

Parameters

  array | Pointer to array.
  type | Type of new array.

Returns
  New array.

Errors

  CPL_ERROR_NULL_INPUT | Input array is a NULL pointer.
  CPL_ERROR_INVALID_TYPE | The specified column is not numerical.
  CPL_ERROR_ILLEGAL_INPUT | The specified type is not numerical.

A new array of the specified type is created, and the content of the input numeric array is cast to the new type. If the input array type is identical to the specified type the array is duplicated as is done by the function `cpl_array_duplicate()`.

References cpl_calloc(), CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_free(), CPL_TYPE_DOUBLE, CPL_TYPE_DOUBLE_COMPLEX, CPL_TYPE_FLOAT, CPL_TYPE_FLOAT_COMPLEX, CPL_TYPE_INT, CPL_TYPE_LONG, CPL_TYPE_LONG_LONG, and CPL_TYPE_SIZE.

## cpl_array_copy_data()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_copy_data_complex()

cpl_error_code cpl_array_copy_data_complex | ( | cpl_array * | array,
|  | const double complex * | data )

Copy buffer of complex data to a complex array.

Parameters

  array | Existing array.
  data | Existing data buffer.

Returns
  `CPL_ERROR_NONE` on success. If the array is not complex, 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_copy_data_cplsize()

cpl_error_code cpl_array_copy_data_cplsize | ( | cpl_array * | array,
|  | const cpl_size * | data )

Copy existing data to a cpl_size 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_SIZE`, 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_copy_data_double()

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_copy_data_double_complex()

cpl_error_code cpl_array_copy_data_double_complex | ( | cpl_array * | array,
|  | const double complex * | data )

Copy existing data to a double complex 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_COMPLEX`, 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()`.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_copy_data_float()

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_copy_data_float_complex()

cpl_error_code cpl_array_copy_data_float_complex | ( | cpl_array * | array,
|  | const float complex * | data )

Copy existing data to a float complex 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_COMPLEX`, 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()`.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_copy_data_long()

cpl_error_code cpl_array_copy_data_long | ( | cpl_array * | array,
|  | const long * | data )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_copy_data_long_long()

cpl_error_code cpl_array_copy_data_long_long | ( | cpl_array * | array,
|  | const long long * | data )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_copy_data_string()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_count_invalid()

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

References CPL_ERROR_NULL_INPUT.

## cpl_array_delete()

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.

References cpl_free().

Referenced by cpl_array_extract(), cpl_fit_image_gaussian(), cpl_matrix_get_determinant(), cpl_matrix_invert_create(), cpl_matrix_solve(), cpl_ppm_match_points(), cpl_table_compare_structure(), cpl_wcs_convert(), cpl_wcs_delete(), and cpl_wcs_platesol().

## cpl_array_divide()

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

Divide the values of two numeric or complex 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_divide_scalar()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_divide_scalar_complex()

cpl_error_code cpl_array_divide_scalar_complex | ( | cpl_array * | array,
|  | double complex | value )

Divide a complex array by a constant complex 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 complex.
  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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_dump()

void cpl_array_dump | ( | const cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | count,
|  | FILE * | stream )

Print an array.

Parameters

  array | Pointer to array
  start | First element to print
  count | Number of elements to print
  stream | The output stream

Returns
  Nothing.

This function is mainly intended for debug purposes. Array elements are counted from 0, and their sequence number is printed at the left of each element. Invalid elements are represented as a sequence of "-" as wide as the field occupied by the array. Specifying a start beyond the array boundaries, or a non-positive count, would generate a warning message, but no error would be set. The specified number of elements to print may exceed the array end, and in that case the array would be printed up to its last element. If the specified stream is `NULL`, it is set to stdout. The function used for printing is the standard C `fprintf()`.

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

## cpl_array_dump_structure()

void cpl_array_dump_structure | ( | const cpl_array * | array,
|  | FILE * | stream )

Describe the structure and the contents of an array.

Parameters

  array | Pointer to array.
  stream | The output stream

Returns
  Nothing.

This function is mainly intended for debug purposes. Some information about the structure of an array and its contents is printed to terminal:

- Data type of the array
- Number of elements
- Number of invalid elements

If the specified stream is `NULL`, it is set to stdout. The function used for printing is the standard C `fprintf()`.

References CPL_SIZE_FORMAT, CPL_TYPE_DOUBLE, CPL_TYPE_DOUBLE_COMPLEX, CPL_TYPE_FLOAT, CPL_TYPE_FLOAT_COMPLEX, CPL_TYPE_INT, CPL_TYPE_LONG, CPL_TYPE_LONG_LONG, CPL_TYPE_SIZE, and CPL_TYPE_STRING.

## cpl_array_duplicate()

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.

References cpl_array_get_size(), cpl_array_get_type(), cpl_array_new(), and CPL_ERROR_NULL_INPUT.

Referenced by cpl_array_extract_imag(), and cpl_array_extract_real().

## cpl_array_erase_window()

cpl_error_code cpl_array_erase_window | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | 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.

References cpl_array_get_size(), CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_exponential()

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 or complex.
  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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_extract()

cpl_array * cpl_array_extract | ( | const cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | count )

Create an array from a section of another array.

Parameters

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

References cpl_array_delete(), cpl_array_get_size(), cpl_array_get_type(), cpl_array_new(), and CPL_ERROR_NULL_INPUT.

## cpl_array_extract_imag()

cpl_array * cpl_array_extract_imag | ( | const cpl_array * | array | ) |

Extract the imaginary value of array elements.

Parameters

  array | Pointer to array.

Returns
  New array with imaginary part of input array elements.

Errors

  CPL_ERROR_NULL_INPUT | Input array is NULL pointer.
  CPL_ERROR_INVALID_TYPE | The specified array is not numerical.

A new array is created with the imaginary part of all input array elements. If the input array is complex, the output type will be CPL_TYPE_FLOAT if input is CPL_TYPE_FLOAT_COMPLEX, and CPL_TYPE_DOUBLE if input is CPL_TYPE_DOUBLE_COMPLEX).

References cpl_array_duplicate(), cpl_array_get_type(), cpl_array_new(), CPL_ERROR_NULL_INPUT, CPL_TYPE_COMPLEX, and CPL_TYPE_FLOAT.

## cpl_array_extract_real()

cpl_array * cpl_array_extract_real | ( | const cpl_array * | array | ) |

Extract the real value of array elements.

Parameters

  array | Pointer to array.

Returns
  New array with real part of input array elements.

Errors

  CPL_ERROR_NULL_INPUT | Input array is NULL pointer.
  CPL_ERROR_INVALID_TYPE | The specified array is not numerical.

A new array is created with the real part of all input array elements. If the input array is complex, the output type will be CPL_TYPE_FLOAT if input is CPL_TYPE_FLOAT_COMPLEX, and CPL_TYPE_DOUBLE if input is CPL_TYPE_DOUBLE_COMPLEX).

References cpl_array_duplicate(), cpl_array_get_type(), cpl_array_new(), CPL_ERROR_NULL_INPUT, CPL_TYPE_COMPLEX, and CPL_TYPE_FLOAT.

## cpl_array_fill_window()

cpl_error_code cpl_array_fill_window | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | 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()`.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_table_where_selected().

## cpl_array_fill_window_complex()

cpl_error_code cpl_array_fill_window_complex | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | count,
|  | double complex | value )

Write the same value within a complex 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 complex 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()`.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_cplsize()

cpl_error_code cpl_array_fill_window_cplsize | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | count,
|  | cpl_size | value )

Write the same value within a cpl_size 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 cpl_size 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_double()

cpl_error_code cpl_array_fill_window_double | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_double_complex()

cpl_error_code cpl_array_fill_window_double_complex | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | count,
|  | double complex | value )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_float()

cpl_error_code cpl_array_fill_window_float | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_float_complex()

cpl_error_code cpl_array_fill_window_float_complex | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | count,
|  | float complex | value )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_int()

cpl_error_code cpl_array_fill_window_int | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_invalid()

cpl_error_code cpl_array_fill_window_invalid | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_long()

cpl_error_code cpl_array_fill_window_long | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | count,
|  | long | value )

Write the same value within a long 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 a long 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_long_long()

cpl_error_code cpl_array_fill_window_long_long | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | count,
|  | long long | value )

Write the same value within a long long 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 a long long 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_fill_window_string()

cpl_error_code cpl_array_fill_window_string | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_get()

double cpl_array_get | ( | const cpl_array * | array,
|  | cpl_size | 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`.

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_complex()

double complex cpl_array_get_complex | ( | const cpl_array * | array,
|  | cpl_size | indx,
|  | int * | null )

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

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_cplsize()

cpl_size cpl_array_get_cplsize | ( | const cpl_array * | array,
|  | cpl_size | indx,
|  | int * | null )

Read a value from a cpl_size array.

Parameters

  array | Array to be accessed.
  indx | Position of element to be read.
  null | Flag indicating null values, or error condition.

Returns
  The cpl_size 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_SIZE`. 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).

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_data_cplsize()

cpl_size * cpl_array_get_data_cplsize | ( | cpl_array * | array | ) |

Get a pointer to `cpl_size` array data.

Parameters

  array | Array to get the data from.

Returns
  Pointer to `cpl_size` 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_SIZE`, 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.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_table_where_selected().

## cpl_array_get_data_cplsize_const()

const cpl_size * cpl_array_get_data_cplsize_const | ( | const cpl_array * | array | ) |

Get a pointer to constant `cpl_size` array data.

Parameters

  array | Constant array to get the data from.

Returns
  Pointer to constant `cpl_size` 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_SIZE`, a `CPL_ERROR_TYPE_MISMATCH` is set.

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_double()

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

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_array_arg().

## cpl_array_get_data_double_complex()

double complex * cpl_array_get_data_double_complex | ( | cpl_array * | array | ) |

Get a pointer to `double` complex array data.

Parameters

  array | Array to get the data from.

Returns
  Pointer to `double` complex 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_COMPLEX`, a `CPL_ERROR_TYPE_MISMATCH` is set.

See documentation of function cpl_array_get_data_int().

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_double_complex_const()

const double complex * cpl_array_get_data_double_complex_const | ( | const cpl_array * | array | ) |

Get a pointer to constant double complex array data.

Parameters

  array | Constant array to get the data from.

Returns
  Pointer to constant double complex 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_COMPLEX`, a `CPL_ERROR_TYPE_MISMATCH` is set.

See documentation of function cpl_array_get_data_int_const().

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_double_const()

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

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_wcs_platesol().

## cpl_array_get_data_float()

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

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_array_arg().

## cpl_array_get_data_float_complex()

float complex * cpl_array_get_data_float_complex | ( | cpl_array * | array | ) |

Get a pointer to `float` complex array data.

Parameters

  array | Array to get the data from.

Returns
  Pointer to `float` complex 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_COMPLEX`, a `CPL_ERROR_TYPE_MISMATCH` is set.

See documentation of function cpl_array_get_data_int().

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_float_complex_const()

const float complex * cpl_array_get_data_float_complex_const | ( | const cpl_array * | array | ) |

Get a pointer to constant float complex array data.

Parameters

  array | Constant array to get the data from.

Returns
  Pointer to constant float complex 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_COMPLEX`, a `CPL_ERROR_TYPE_MISMATCH` is set.

See documentation of function cpl_array_get_data_int_const().

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_float_const()

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

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_int()

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.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_wcs_convert().

## cpl_array_get_data_int_const()

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.

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_long()

long * cpl_array_get_data_long | ( | cpl_array * | array | ) |

Get a pointer to `long` `integer` array data.

Parameters

  array | Array to get the data from.

Returns
  Pointer to `long` `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_LONG`, 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.

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_long_const()

const long * cpl_array_get_data_long_const | ( | const cpl_array * | array | ) |

Get a pointer to constant `long` `integer` array data.

Parameters

  array | Constant array to get the data from.

Returns
  Pointer to constant `long` `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_LONG`, a `CPL_ERROR_TYPE_MISMATCH` is set.

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_long_long()

long long * cpl_array_get_data_long_long | ( | cpl_array * | array | ) |

Get a pointer to `long` `long` `integer` array data.

Parameters

  array | Array to get the data from.

Returns
  Pointer to `long` `long` `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_LONG_LONG`, 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.

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_long_long_const()

const long long * cpl_array_get_data_long_long_const | ( | const cpl_array * | array | ) |

Get a pointer to constant `long` `long` `integer` array data.

Parameters

  array | Constant array to get the data from.

Returns
  Pointer to constant `long` `long` `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_LONG_LONG`, a `CPL_ERROR_TYPE_MISMATCH` is set.

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_string()

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

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_data_string_const()

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

References CPL_ERROR_NULL_INPUT.

## cpl_array_get_double()

double cpl_array_get_double | ( | const cpl_array * | array,
|  | cpl_size | 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().

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

Referenced by cpl_fit_image_gaussian(), and cpl_gaussian_eval_2d().

## cpl_array_get_double_complex()

double complex cpl_array_get_double_complex | ( | const cpl_array * | array,
|  | cpl_size | indx,
|  | int * | null )

Read a value from a double complex 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_COMPLEX`. See the documentation of the function cpl_array_get_int().

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_float()

float cpl_array_get_float | ( | const cpl_array * | array,
|  | cpl_size | 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().

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_float_complex()

float complex cpl_array_get_float_complex | ( | const cpl_array * | array,
|  | cpl_size | indx,
|  | int * | null )

Read a value from a float complex 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_COMPLEX`. See the documentation of the function cpl_array_get_int().

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_int()

int cpl_array_get_int | ( | const cpl_array * | array,
|  | cpl_size | 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).

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

Referenced by cpl_fit_image_gaussian(), and cpl_wcs_duplicate().

## cpl_array_get_long()

long cpl_array_get_long | ( | const cpl_array * | array,
|  | cpl_size | indx,
|  | int * | null )

Read a value from a long integer array.

Parameters

  array | Array to be accessed.
  indx | Position of element to be read.
  null | Flag indicating null values, or error condition.

Returns
  Long 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_LONG`. 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).

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_long_long()

long long cpl_array_get_long_long | ( | const cpl_array * | array,
|  | cpl_size | indx,
|  | int * | null )

Read a value from a long long integer array.

Parameters

  array | Array to be accessed.
  indx | Position of element to be read.
  null | Flag indicating null values, or error condition.

Returns
  Long long integer value read. In case of an invalid array element, or in case of error, 0 is returned.

Read a value from an array of type `CPL_TYPE_LONG_LONG`. 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).

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_max()

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 or complex are not allowed.

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_maxpos()

cpl_error_code cpl_array_get_maxpos | ( | const cpl_array * | array,
|  | cpl_size * | 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 or complex are not allowed.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_get_mean()

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 or complex are not allowed.

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_mean_complex()

double complex cpl_array_get_mean_complex | ( | const cpl_array * | array | ) |

Compute the mean value of a complex 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 complex.
  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 or numerical are not allowed.

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_median()

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 or complex are not allowed.

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_min()

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 or complex are not allowed.

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_minpos()

cpl_error_code cpl_array_get_minpos | ( | const cpl_array * | array,
|  | cpl_size * | 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 or complex are not allowed.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_get_size()

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

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_array_arg(), cpl_array_duplicate(), cpl_array_erase_window(), cpl_array_extract(), and cpl_gaussian_eval_2d().

## cpl_array_get_stdev()

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 or complex are not allowed.

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_get_string()

const char * cpl_array_get_string | ( | const cpl_array * | array,
|  | cpl_size | 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()`.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_table_compare_structure().

## cpl_array_get_type()

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.

References CPL_ERROR_NULL_INPUT, cpl_error_set, and CPL_TYPE_INVALID.

Referenced by cpl_array_abs(), cpl_array_arg(), cpl_array_duplicate(), cpl_array_extract(), cpl_array_extract_imag(), cpl_array_extract_real(), and cpl_fit_image_gaussian().

## cpl_array_has_invalid()

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.

References CPL_ERROR_NULL_INPUT.

## cpl_array_has_valid()

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.

References CPL_ERROR_NULL_INPUT.

## cpl_array_insert()

cpl_error_code cpl_array_insert | ( | cpl_array * | target_array,
|  | const cpl_array * | insert_array,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_insert_window()

cpl_error_code cpl_array_insert_window | ( | cpl_array * | array,
|  | cpl_size | start,
|  | cpl_size | count )

Insert a segment of new elements into array.

Parameters

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_is_valid()

int cpl_array_is_valid | ( | const cpl_array * | array,
|  | cpl_size | indx )

Check if an array element is valid.

Parameters

  array | Pointer to array.
  indx | Array element to examine.

Returns
  1 if the array element is valid, 0 if invalid, -1 in case of 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 indx is outside the array boundaries.

Check if an array element is valid.

References CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), and cpl_errorstate_is_equal().

## cpl_array_logarithm()

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 or complex.
  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. In case of complex numbers, values very close to the origin may cause an overflow.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_multiply()

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

Multiply the values of two numeric or complex 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_multiply_scalar()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_multiply_scalar_complex()

cpl_error_code cpl_array_multiply_scalar_complex | ( | cpl_array * | array,
|  | double complex | value )

Multiply a complex array by a constant complex 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 complex.

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_new()

cpl_array * cpl_array_new | ( | cpl_size | 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`, `CPL_TYPE_FLOAT_COMPLEX`, `CPL_TYPE_DOUBLE_COMPLEX` 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.

References cpl_calloc(), CPL_ERROR_INVALID_TYPE, CPL_TYPE_DOUBLE, CPL_TYPE_DOUBLE_COMPLEX, CPL_TYPE_FLOAT, CPL_TYPE_FLOAT_COMPLEX, cpl_type_get_name(), CPL_TYPE_INT, CPL_TYPE_LONG, CPL_TYPE_LONG_LONG, CPL_TYPE_SIZE, and CPL_TYPE_STRING.

Referenced by cpl_array_duplicate(), cpl_array_extract(), cpl_array_extract_imag(), cpl_array_extract_real(), cpl_fit_image_gaussian(), cpl_table_get_column_names(), cpl_table_where_selected(), and cpl_wcs_convert().

## cpl_array_power()

cpl_error_code cpl_array_power | ( | cpl_array * | array,
|  | double | exponent )

Compute the power of numerical array elements.

Parameters

  array | Pointer to numerical array.
  exponent | Constant exponent.

Returns
  `CPL_ERROR_NONE` on success.

See also
  pow(), cpow()

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_power_complex()

cpl_error_code cpl_array_power_complex | ( | cpl_array * | array,
|  | double complex | exponent )

Compute the complex power of complex, numerical array elements.

Parameters

  array | Pointer to numerical array.
  exponent | Constant exponent.

Returns
  `CPL_ERROR_NONE` on success.

See also
  cpl_array_power()

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set()

cpl_error_code cpl_array_set | ( | cpl_array * | array,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set_complex()

cpl_error_code cpl_array_set_complex | ( | cpl_array * | array,
|  | cpl_size | indx,
|  | double complex | value )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set_cplsize()

cpl_error_code cpl_array_set_cplsize | ( | cpl_array * | array,
|  | cpl_size | indx,
|  | cpl_size | value )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set_double()

cpl_error_code cpl_array_set_double | ( | cpl_array * | array,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_fit_image_gaussian().

## cpl_array_set_double_complex()

cpl_error_code cpl_array_set_double_complex | ( | cpl_array * | array,
|  | cpl_size | indx,
|  | double complex | value )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set_float()

cpl_error_code cpl_array_set_float | ( | cpl_array * | array,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set_float_complex()

cpl_error_code cpl_array_set_float_complex | ( | cpl_array * | array,
|  | cpl_size | indx,
|  | float complex | value )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set_int()

cpl_error_code cpl_array_set_int | ( | cpl_array * | array,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_wcs_duplicate().

## cpl_array_set_invalid()

cpl_error_code cpl_array_set_invalid | ( | cpl_array * | array,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_fit_image_gaussian().

## cpl_array_set_long()

cpl_error_code cpl_array_set_long | ( | cpl_array * | array,
|  | cpl_size | indx,
|  | long | value )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set_long_long()

cpl_error_code cpl_array_set_long_long | ( | cpl_array * | array,
|  | cpl_size | indx,
|  | long long | value )

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set_size()

cpl_error_code cpl_array_set_size | ( | cpl_array * | array,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_set_string()

cpl_error_code cpl_array_set_string | ( | cpl_array * | array,
|  | cpl_size | 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_table_get_column_names().

## cpl_array_subtract()

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

Subtract the values of two numeric or complex 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_subtract_scalar()

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_subtract_scalar_complex()

cpl_error_code cpl_array_subtract_scalar_complex | ( | cpl_array * | array,
|  | double complex | value )

Subtract a constant complex value from a complex 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 complex.

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_array_unwrap()

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.

References cpl_free().

Referenced by cpl_wcs_delete().

## cpl_array_wrap_cplsize()

cpl_array * cpl_array_wrap_cplsize | ( | cpl_size * | data,
|  | cpl_size | length )

Create a new cpl_size 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 cpl_size 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 dynamically 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.

References cpl_calloc().

## cpl_array_wrap_double()

cpl_array * cpl_array_wrap_double | ( | double * | data,
|  | cpl_size | 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()`.

References cpl_calloc().

## cpl_array_wrap_double_complex()

cpl_array * cpl_array_wrap_double_complex | ( | double complex * | data,
|  | cpl_size | length )

Create a new double complex 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()`.

References cpl_calloc().

## cpl_array_wrap_float()

cpl_array * cpl_array_wrap_float | ( | float * | data,
|  | cpl_size | 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()`.

References cpl_calloc().

## cpl_array_wrap_float_complex()

cpl_array * cpl_array_wrap_float_complex | ( | float complex * | data,
|  | cpl_size | length )

Create a new float complex 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()`.

References cpl_calloc().

## cpl_array_wrap_int()

cpl_array * cpl_array_wrap_int | ( | int * | data,
|  | cpl_size | 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 dynamically 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.

References cpl_calloc().

Referenced by cpl_matrix_get_determinant(), cpl_matrix_invert_create(), cpl_matrix_solve(), and cpl_wcs_platesol().

## cpl_array_wrap_long()

cpl_array * cpl_array_wrap_long | ( | long * | data,
|  | cpl_size | length )

Create a new long 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 long 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 dynamically 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.

References cpl_calloc().

## cpl_array_wrap_long_long()

cpl_array * cpl_array_wrap_long_long | ( | long long * | data,
|  | cpl_size | length )

Create a new long long 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 long long 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 dynamically 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.

References cpl_calloc().

## cpl_array_wrap_string()

cpl_array * cpl_array_wrap_string | ( | char ** | data,
|  | cpl_size | 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()`.

References cpl_calloc().