Common Pipeline Library Reference Manual
6.1.1
|
Defines | |
#define | cpl_test(bool) |
Evaluate an expression and increment an internal counter if zero. | |
#define | cpl_test_abs(first, second, tolerance) |
Test if two numerical expressions are within a given absolute tolerance. | |
#define | cpl_test_array_abs(first, second, tolerance) |
Test if two numerical arrays are identical within a given (absolute) tolerance. | |
#define | cpl_test_assert(bool) |
Evaluate an expression and return if it fails. | |
#define | cpl_test_eq(first, second) |
Test if two integer expressions are equal. | |
#define | cpl_test_eq_error(first, second) |
Test if two error expressions are equal and reset the CPL error code. | |
#define | cpl_test_eq_mask(first, second) |
Test if two CPL masks are equal. | |
#define | cpl_test_eq_ptr(first, second) |
Test if two pointer expressions are equal. | |
#define | cpl_test_eq_string(first, second) |
Test if two strings are equal. | |
#define | cpl_test_error(error) |
Test and reset the CPL error code. | |
#define | cpl_test_errorstate(errorstate) |
Test and if necessary reset the CPL errorstate. | |
#define | cpl_test_fits(fitsfile) |
Test if a file is valid FITS using an external verification utility. | |
#define | cpl_test_image_abs(first, second, tolerance) |
Test if two images are identical within a given (absolute) tolerance. | |
#define | cpl_test_imagelist_abs(first, second, tolerance) |
Test if two imagelists are identical within a given (absolute) tolerance. | |
#define | cpl_test_init(REPORT, LEVEL) |
Initialize CPL + CPL messaging + unit test. | |
#define | cpl_test_leq(value, tolerance) |
Evaluate A <= B and increment an internal counter if it is not true. | |
#define | cpl_test_lt(value, tolerance) |
Evaluate A < B and increment an internal counter if it is not true. | |
#define | cpl_test_matrix_abs(first, second, tolerance) |
Test if two matrices are identical within a given (absolute) tolerance. | |
#define | cpl_test_memory_is_empty() |
Test if the memory system is empty. | |
#define | cpl_test_noneq(first, second) |
Test if two integer expressions are not equal. | |
#define | cpl_test_noneq_ptr(first, second) |
Test if two pointer expressions are not equal. | |
#define | cpl_test_noneq_string(first, second) |
Test if two strings are not equal. | |
#define | cpl_test_nonnull(pointer) |
Test if a pointer is non-NULL. | |
#define | cpl_test_null(pointer) |
Test if a pointer is NULL and update an internal counter on failure. | |
#define | cpl_test_polynomial_abs(first, second, tolerance) |
Test if two polynomials are identical within a given (absolute) tolerance. | |
#define | cpl_test_rel(first, second, tolerance) |
Test if two numerical expressions are within a given relative tolerance. | |
#define | cpl_test_vector_abs(first, second, tolerance) |
Test if two vectors are identical within a given (absolute) tolerance. | |
#define | cpl_test_zero(zero) |
Evaluate an expression and increment an internal counter if non-zero. | |
Functions | |
int | cpl_test_end (cpl_size nfail) |
Finalize CPL and unit-testing environment and report any failures. | |
size_t | cpl_test_get_bytes_image (const cpl_image *self) |
Get the amount of storage [bytes] for the CPL object. | |
size_t | cpl_test_get_bytes_imagelist (const cpl_imagelist *self) |
Get the amount of storage [bytes] for the CPL object. | |
size_t | cpl_test_get_bytes_matrix (const cpl_matrix *self) |
Get the amount of storage [bytes] for the CPL object. | |
size_t | cpl_test_get_bytes_vector (const cpl_vector *self) |
Get the amount of storage [bytes] for the CPL object. | |
double | cpl_test_get_walltime (void) |
Get the process wall-clock time, when available (from gettimeofday()) |
This module provides various functions for unit testing.
#include "cpl_test.h"
#define cpl_test | ( | bool | ) |
Evaluate an expression and increment an internal counter if zero.
bool | The expression to evaluate, side-effects are allowed |
Example of usage:
cpl_test(myfunc()); // myfunc() is expected to return non-zero
#define cpl_test_abs | ( | first, | |
second, | |||
tolerance | |||
) |
Test if two numerical expressions are within a given absolute tolerance.
first | The first value in the comparison, side-effects are allowed |
second | The second value in the comparison, side-effects are allowed |
tolerance | A non-negative tolerance |
Example of usage:
cpl_test_abs(computed, expected, DBL_EPSILON);
#define cpl_test_array_abs | ( | first, | |
second, | |||
tolerance | |||
) |
Test if two numerical arrays are identical within a given (absolute) tolerance.
first | The first array in the comparison |
second | The second array of identical size in the comparison |
tolerance | A non-negative tolerance |
#define cpl_test_assert | ( | bool | ) |
Evaluate an expression and return if it fails.
bool | The (boolean) expression to evaluate, side-effects are allowed |
Example of usage:
int main (void) { cpl_test_init(CPL_MSG_WARNING); cpl_test(myfunc(&p)); cpl_test_assert(p != NULL); cpl_test(*p); return cpl_test_end(0); }
#define cpl_test_eq | ( | first, | |
second | |||
) |
Test if two integer expressions are equal.
first | The first value in the comparison, side-effects are allowed |
second | The second value in the comparison, side-effects are allowed |
Example of usage:
cpl_test_eq(computed, expected);
For comparison of floating point values, see cpl_test_abs() and cpl_test_rel().
#define cpl_test_eq_error | ( | first, | |
second | |||
) |
Test if two error expressions are equal and reset the CPL error code.
first | The first value in the comparison |
second | The second value in the comparison |
Example of usage:
cpl_error_code error = my_func(NULL); // my_func(NULL) is expected to return CPL_ERROR_NULL_INPUT // and to set the same error code cpl_test_eq_error(error, CPL_ERROR_NULL_INPUT); // The errorstate has been reset. error = my_func(p); // Successful call cpl_test_eq_error(error, CPL_ERROR_NONE);
#define cpl_test_eq_mask | ( | first, | |
second | |||
) |
Test if two CPL masks are equal.
first | The first mask or NULL of the comparison |
second | The second mask or NULL of the comparison |
Example of usage:
cpl_test_eq_mask(computed, expected);
#define cpl_test_eq_ptr | ( | first, | |
second | |||
) |
Test if two pointer expressions are equal.
first | The first value in the comparison, side-effects are allowed |
second | The second value in the comparison, side-effects are allowed |
Example of usage:
cpl_test_eq_ptr(computed, expected);
#define cpl_test_eq_string | ( | first, | |
second | |||
) |
Test if two strings are equal.
first | The first string or NULL of the comparison |
second | The second string or NULL of the comparison |
Example of usage:
cpl_test_eq_string(computed, expected);
#define cpl_test_error | ( | error | ) |
Test and reset the CPL error code.
error | The expected CPL error code (incl. CPL_ERROR_NONE) |
Example of usage:
cpl_test( my_func(NULL) ); // my_func(NULL) is expected to return non-zero cpl_test_error(CPL_ERROR_NULL_INPUT); // ... and to set this error code // The errorstate has been reset. cpl_test( !my_func(p) ); // my_func(p) is expected to return zero
#define cpl_test_errorstate | ( | errorstate | ) |
Test and if necessary reset the CPL errorstate.
errorstate | The expected CPL errorstate |
This function is useful for verifying that a successful call to a function does not modify any pre-existing errors.
Example of usage:
const cpl_error_code error = cpl_error_set(cpl_func, CPL_ERROR_EOL); cpl_errorstate prestate = cpl_errorstate_get(); const cpl_error_code ok = my_func(); // Expected to succeed cpl_test_errorstate(prestate); // Verify that no additional errors occurred cpl_test_error(CPL_ERROR_EOL); // Reset error cpl_test_eq(ok, CPL_ERROR_NONE); // Verify that my_func() succeeded
#define cpl_test_fits | ( | fitsfile | ) |
Test if a file is valid FITS using an external verification utility.
fitsfile | The file to verify, NULL causes failure |
Example of usage:
export CPL_TEST_FITS=/usr/local/bin/fitsverify
cpl_test_fits(fitsfile);
#define cpl_test_image_abs | ( | first, | |
second, | |||
tolerance | |||
) |
Test if two images are identical within a given (absolute) tolerance.
first | The first image in the comparison |
second | The second image of identical size in the comparison |
tolerance | A non-negative tolerance |
#define cpl_test_imagelist_abs | ( | first, | |
second, | |||
tolerance | |||
) |
Test if two imagelists are identical within a given (absolute) tolerance.
first | The first imagelist in the comparison |
second | The second imagelist of identical size in the comparison |
tolerance | A non-negative tolerance |
#define cpl_test_init | ( | REPORT, | |
LEVEL | |||
) |
Initialize CPL + CPL messaging + unit test.
REPORT | The email address for the error message e.g. PACKAGE_BUGREPORT |
LEVEL | The default messaging level, e.g. CPL_MSG_WARNING |
#define cpl_test_leq | ( | value, | |
tolerance | |||
) |
Evaluate A <= B and increment an internal counter if it is not true.
value | The number to test |
tolerance | The upper limit to compare against |
Example of usage:
cpl_test_leq(fabs(myfunc(&p)), DBL_EPSILON); cpl_test_nonnull(p);
#define cpl_test_lt | ( | value, | |
tolerance | |||
) |
Evaluate A < B and increment an internal counter if it is not true.
value | The number to test |
tolerance | The upper limit to compare against |
Example of usage:
cpl_test_lt(0.0, myfunc());
#define cpl_test_matrix_abs | ( | first, | |
second, | |||
tolerance | |||
) |
Test if two matrices are identical within a given (absolute) tolerance.
first | The first matrix in the comparison |
second | The second matrix of identical size in the comparison |
tolerance | A non-negative tolerance |
#define cpl_test_memory_is_empty | ( | ) |
Test if the memory system is empty.
#define cpl_test_noneq | ( | first, | |
second | |||
) |
Test if two integer expressions are not equal.
first | The first value in the comparison, side-effects are allowed |
second | The second value in the comparison, side-effects are allowed |
Example of usage:
cpl_test_noneq(computed, wrong);
#define cpl_test_noneq_ptr | ( | first, | |
second | |||
) |
Test if two pointer expressions are not equal.
first | The first value in the comparison, side-effects are allowed |
second | The second value in the comparison, side-effects are allowed |
Example of usage:
cpl_test_noneq_ptr(computed, wrong);
#define cpl_test_noneq_string | ( | first, | |
second | |||
) |
Test if two strings are not equal.
first | The first string or NULL of the comparison |
second | The second string or NULL of the comparison |
Example of usage:
cpl_test_noneq_string(computed, expected);
#define cpl_test_nonnull | ( | pointer | ) |
Test if a pointer is non-NULL.
pointer | The pointer to check, side-effects are allowed |
Example of usage:
cpl_test_nonnull(pointer); // pointer is expected to be non-NULL
#define cpl_test_null | ( | pointer | ) |
Test if a pointer is NULL and update an internal counter on failure.
pointer | The NULL-pointer to check, side-effects are allowed |
Example of usage:
cpl_test_null(pointer); // pointer is expected to be NULL
#define cpl_test_polynomial_abs | ( | first, | |
second, | |||
tolerance | |||
) |
Test if two polynomials are identical within a given (absolute) tolerance.
first | The first polynomial in the comparison |
second | The second polynomial in the comparison |
tolerance | A non-negative tolerance |
#define cpl_test_rel | ( | first, | |
second, | |||
tolerance | |||
) |
Test if two numerical expressions are within a given relative tolerance.
first | The first value in the comparison, side-effects are allowed |
second | The second value in the comparison, side-effects are allowed |
tolerance | A non-negative tolerance |
The test is carried out by comparing the absolute value of the difference abs (first - second) to the product of the tolerance and the minimum of the absolute value of the two values, tolerance * min(abs(first), abs(second)) (The test is implemented like this to avoid division with a number that may be zero.
Example of usage:
cpl_test_rel(computed, expected, 0.001);
#define cpl_test_vector_abs | ( | first, | |
second, | |||
tolerance | |||
) |
Test if two vectors are identical within a given (absolute) tolerance.
first | The first vector in the comparison |
second | The second vector of identical size in the comparison |
tolerance | A non-negative tolerance |
#define cpl_test_zero | ( | zero | ) |
Evaluate an expression and increment an internal counter if non-zero.
zero | The numerical expression to evaluate, side-effects are allowed |
Example of usage:
cpl_test_zero(myfunc()); // myfunc() is expected to return zero
int cpl_test_end | ( | cpl_size | nfail | ) |
Finalize CPL and unit-testing environment and report any failures.
nfail | The number of failures counted apart from cpl_test() et al. |
nfail should normally be zero, but may be set to a positive number when it is necessary to ensure a failure. nfail should only be negative in the unit test of the unit-test functions themselves.
Example of usage:
int main (void) { cpl_test_init(PACKAGE_BUGREPORT, CPL_MSG_WARNING); cpl_test(myfunc(&p)); cpl_test(p != NULL); return cpl_test_end(0); }
size_t cpl_test_get_bytes_image | ( | const cpl_image * | self | ) |
Get the amount of storage [bytes] for the CPL object.
self | The CPL object |
size_t cpl_test_get_bytes_imagelist | ( | const cpl_imagelist * | self | ) |
Get the amount of storage [bytes] for the CPL object.
self | The CPL object |
size_t cpl_test_get_bytes_matrix | ( | const cpl_matrix * | self | ) |
Get the amount of storage [bytes] for the CPL object.
self | The CPL object |
size_t cpl_test_get_bytes_vector | ( | const cpl_vector * | self | ) |
Get the amount of storage [bytes] for the CPL object.
self | The CPL object |
Example of usage:
int my_benchmark (void) { const size_t storage = cpl_test_get_bytes_vector(mydata); double walltime, tstop; const double tstart = cpl_test_get_walltime(); myfunc(mydata); tstop = cpl_test_get_walltime(); walltime = tstop - tstart; if (walltime > 0.0) { cpl_msg_info(cpl_func, "Processing rate: %g", (double)storage/walltime); } }
double cpl_test_get_walltime | ( | void | ) |
Get the process wall-clock time, when available (from gettimeofday())
Example of usage:
int my_benchmark (void) { double walltime, tstop; const double tstart = cpl_test_get_walltime(); myfunc(); tstop = cpl_test_get_walltime(); walltime = tstop - tstart; cpl_msg_info(cpl_func, "The call took %g seconds of wall-clock time", walltime); }