wcsutil.h File Reference

Go to the source code of this file.

Functions
void	wcsdealloc (void *ptr)
	free memory allocated by WCSLIB functions.
void	wcsutil_strcvt (int n, char c, int nt, const char src[], char dst[])
	Copy character string with padding.
void	wcsutil_blank_fill (int n, char c[])
	Fill a character string with blanks.
void	wcsutil_null_fill (int n, char c[])
	Fill a character string with NULLs.
int	wcsutil_all_ival (int nelem, int ival, const int iarr[])
	Test if all elements an int array have a given value.
int	wcsutil_all_dval (int nelem, double dval, const double darr[])
	Test if all elements a double array have a given value.
int	wcsutil_all_sval (int nelem, const char *sval, const char(*sarr)[72])
	Test if all elements a string array have a given value.
int	wcsutil_allEq (int nvec, int nelem, const double *first)
	Test for equality of a particular vector element.
int	wcsutil_dblEq (int nelem, double tol, const double *arr1, const double *arr2)
	Test for equality of two arrays of type double.
int	wcsutil_intEq (int nelem, const int *arr1, const int *arr2)
	Test for equality of two arrays of type int.
int	wcsutil_strEq (int nelem, char(*arr1)[72], char(*arr2)[72])
	Test for equality of two string arrays.
void	wcsutil_setAll (int nvec, int nelem, double *first)
	Set a particular vector element.
void	wcsutil_setAli (int nvec, int nelem, int *first)
	Set a particular vector element.
void	wcsutil_setBit (int nelem, const int *sel, int bits, int *array)
	Set bits in selected elements of an array.
char *	wcsutil_fptr2str (void(*fptr)(void), char hext[19])
	Translate pointer-to-function to string.
void	wcsutil_double2str (char *buf, const char *format, double value)
	Translate double to string ignoring the locale.
int	wcsutil_str2double (const char *buf, double *value)
	Translate string to a double, ignoring the locale.
int	wcsutil_str2double2 (const char *buf, double *value)
	Translate string to doubles, ignoring the locale.

Detailed Description

Simple utility functions. With the exception of wcsdealloc(), these functions are intended for internal use only by WCSLIB.

The internal-use functions are documented here solely as an aid to understanding the code. They are not intended for external use - the API may change without notice!

Function Documentation

wcsdealloc()

void wcsdealloc

(

void *

ptr

)

free memory allocated by WCSLIB functions.

wcsdealloc() invokes the free() system routine to free memory. Specifically, it is intended to free memory allocated (using calloc()) by certain WCSLIB functions (e.g. wcshdo(), wcsfixi(), fitshdr()), which it is the user's responsibility to deallocate.

In certain situations, for example multithreading, it may be important that this be done within the WCSLIB sharable library's runtime environment.

PLEASE NOTE: wcsdealloc() must not be used in place of the destructors for particular structs, such as wcsfree(), celfree(), etc.

Parameters

[in,out]

ptr

Address of the allocated memory.

Returns

wcsutil_strcvt()

void wcsutil_strcvt	(	int	n,
		char	c,
		int	nt,
		const char	src[],
		char	dst[] )

Copy character string with padding.

INTERNAL USE ONLY.

wcsutil_strcvt() copies one character string to another up to the specified maximum number of characters.

If the given string is null-terminated, then the NULL character copied to the returned string, and all characters following it up to the specified maximum, are replaced with the specified substitute character, either blank or NULL.

If the source string is not null-terminated and the substitute character is blank, then copy the maximum number of characters and do nothing further. However, if the substitute character is NULL, then the last character and all consecutive blank characters preceding it will be replaced with NULLs.

Used by the Fortran wrapper functions in translating C strings into Fortran CHARACTER variables and vice versa.

Parameters

[in]	n	Maximum number of characters to copy.
[in]	c	Substitute character, either NULL or blank (anything other than NULL).
[in]	nt	If true, then dst is of length n+1, with the last character always set to NULL.
[in]	src	Character string to be copied. If null-terminated, then need not be of length n, otherwise it must be.
[out]	dst	Destination character string, which must be long enough to hold n characters. Note that this string will not be null-terminated if the substitute character is blank.

Returns

wcsutil_blank_fill()

void wcsutil_blank_fill	(	int	n,
		char	c[] )

Fill a character string with blanks.

INTERNAL USE ONLY.

wcsutil_blank_fill() pads a character sub-string with blanks starting with the terminating NULL character (if any).

Parameters

[in]	n	Length of the sub-string.
[in,out]	c	The character sub-string, which will not be null-terminated on return.

Returns

wcsutil_null_fill()

void wcsutil_null_fill	(	int	n,
		char	c[] )

Fill a character string with NULLs.

INTERNAL USE ONLY.

wcsutil_null_fill() strips trailing blanks from a string (or sub-string) and propagates the terminating NULL character (if any) to the end of the string.

If the string is not null-terminated, then the last character and all consecutive blank characters preceding it will be replaced with NULLs.

Mainly used in the C library to strip trailing blanks from FITS keyvalues. Also used to make character strings intelligible in the GNU debugger, which prints the rubbish following the terminating NULL character, thereby obscuring the valid part of the string.

Parameters

[in]	n	Number of characters.
[in,out]	c	The character (sub-)string.

Returns

wcsutil_all_ival()

int wcsutil_all_ival	(	int	nelem,
		int	ival,
		const int	iarr[] )

Test if all elements an int array have a given value.

INTERNAL USE ONLY.

wcsutil_all_ival() tests whether all elements of an array of type int all have the specified value.

Parameters

[in]	nelem	The length of the array.
[in]	ival	Value to be tested.
[in]	iarr	Pointer to the first element of the array.

Returns

Status return value:

• 0: Not all equal.
• 1: All equal.

wcsutil_all_dval()

int wcsutil_all_dval	(	int	nelem,
		double	dval,
		const double	darr[] )

Test if all elements a double array have a given value.

INTERNAL USE ONLY.

wcsutil_all_dval() tests whether all elements of an array of type double all have the specified value.

Parameters

[in]	nelem	The length of the array.
[in]	dval	Value to be tested.
[in]	darr	Pointer to the first element of the array.

Returns

Status return value:

• 0: Not all equal.
• 1: All equal.

wcsutil_all_sval()

int wcsutil_all_sval	(	int	nelem,
		const char *	sval,
		const char(*)	sarr[72] )

Test if all elements a string array have a given value.

INTERNAL USE ONLY.

wcsutil_all_sval() tests whether the elements of an array of type char (*)[72] all have the specified value.

Parameters

[in]	nelem	The length of the array.
[in]	sval	String to be tested.
[in]	sarr	Pointer to the first element of the array.

Returns

Status return value:

• 0: Not all equal.
• 1: All equal.

wcsutil_allEq()

int wcsutil_allEq	(	int	nvec,
		int	nelem,
		const double *	first )

Test for equality of a particular vector element.

INTERNAL USE ONLY.

wcsutil_allEq() tests for equality of a particular element in a set of vectors.

Parameters

[in]	nvec	The number of vectors.
[in]	nelem	The length of each vector.
[in]	first	Pointer to the first element to test in the array. The elements tested for equality are *first == *(first + nelem) == *(first + nelem*2) : == *(first + nelem*(nvec-1)); The array might be dimensioned as double v[nvec][nelem];

Returns

Status return value:

• 0: Not all equal.
• 1: All equal.

wcsutil_dblEq()

int wcsutil_dblEq	(	int	nelem,
		double	tol,
		const double *	arr1,
		const double *	arr2 )

Test for equality of two arrays of type double.

INTERNAL USE ONLY.

wcsutil_dblEq() tests for equality of two double-precision arrays.

Parameters

[in]	nelem	The number of elements in each array.
[in]	tol	Tolerance for comparison of the floating-point values. For example, for tol == 1e-6, all floating-point values in the arrays must be equal to the first 6 decimal places. A value of 0 implies exact equality.
[in]	arr1	The first array.
[in]	arr2	The second array

Returns

Status return value:

• 0: Not equal.
• 1: Equal.

wcsutil_intEq()

int wcsutil_intEq	(	int	nelem,
		const int *	arr1,
		const int *	arr2 )

Test for equality of two arrays of type int.

INTERNAL USE ONLY.

wcsutil_intEq() tests for equality of two int arrays.

Parameters

[in]	nelem	The number of elements in each array.
[in]	arr1	The first array.
[in]	arr2	The second array

Returns

Status return value:

• 0: Not equal.
• 1: Equal.

wcsutil_strEq()

int wcsutil_strEq	(	int	nelem,
		char(*)	arr1[72],
		char(*)	arr2[72] )

Test for equality of two string arrays.

INTERNAL USE ONLY.

wcsutil_strEq() tests for equality of two string arrays.

Parameters

[in]	nelem	The number of elements in each array.
[in]	arr1	The first array.
[in]	arr2	The second array

Returns

Status return value:

• 0: Not equal.
• 1: Equal.

wcsutil_setAll()

void wcsutil_setAll	(	int	nvec,
		int	nelem,
		double *	first )

Set a particular vector element.

INTERNAL USE ONLY.

wcsutil_setAll() sets the value of a particular element in a set of vectors of type double.

Parameters

[in]	nvec	The number of vectors.
[in]	nelem	The length of each vector.
[in,out]	first	Pointer to the first element in the array, the value of which is used to set the others *(first + nelem) = *first; *(first + nelem*2) = *first; : *(first + nelem*(nvec-1)) = *first; The array might be dimensioned as double v[nvec][nelem];

Returns

wcsutil_setAli()

void wcsutil_setAli	(	int	nvec,
		int	nelem,
		int *	first )

Set a particular vector element.

INTERNAL USE ONLY.

wcsutil_setAli() sets the value of a particular element in a set of vectors of type int.

Parameters

[in]	nvec	The number of vectors.
[in]	nelem	The length of each vector.
[in,out]	first	Pointer to the first element in the array, the value of which is used to set the others *(first + nelem) = *first; *(first + nelem*2) = *first; : *(first + nelem*(nvec-1)) = *first; The array might be dimensioned as int v[nvec][nelem];

Returns

wcsutil_setBit()

void wcsutil_setBit	(	int	nelem,
		const int *	sel,
		int	bits,
		int *	array )

Set bits in selected elements of an array.

INTERNAL USE ONLY.

wcsutil_setBit() sets bits in selected elements of an array.

Parameters

[in]	nelem	Number of elements in the array.
[in]	sel	Address of a selection array of length nelem. May be specified as the null pointer in which case all elements are selected.
[in]	bits	Bit mask.
[in,out]	array	Address of the array of length nelem.

Returns

wcsutil_fptr2str()

char * wcsutil_fptr2str	(	void(*	fptr )(void),
		char	hext[19] )

Translate pointer-to-function to string.

INTERNAL USE ONLY.

wcsutil_fptr2str() translates a pointer-to-function to hexadecimal string representation for output. It is used by the various routines that print the contents of WCSLIB structs, noting that it is not strictly legal to type-pun a function pointer to void*. See http://stackoverflow.com/questions/2741683/how-to-format-a-function-pointer

Parameters

[in]	fptr
[out]	hext	Null-terminated string. Should be at least 19 bytes in size to accomodate a 64-bit address (16 bytes in hex), plus the leading "0x" and trailing '\0'.

Returns

The address of hext.

wcsutil_double2str()

void wcsutil_double2str	(	char *	buf,
		const char *	format,
		double	value )

Translate double to string ignoring the locale.

INTERNAL USE ONLY.

wcsutil_double2str() converts a double to a string, but unlike sprintf() it ignores the locale and always uses a '.' as the decimal separator. Also, unless it includes an exponent, the formatted value will always have a fractional part, ".0" being appended if necessary.

Parameters

[out]	buf	The buffer to write the string into.
[in]	format	The formatting directive, such as "f". This may be any of the forms accepted by sprintf(), but should only include a formatting directive and nothing else. For "g" and "G" formats, unless it includes an exponent, the formatted value will always have a fractional part, ".0" being appended if necessary.
[in]	value	The value to convert to a string.

wcsutil_str2double()

int wcsutil_str2double	(	const char *	buf,
		double *	value )

Translate string to a double, ignoring the locale.

INTERNAL USE ONLY.

wcsutil_str2double() converts a string to a double, but unlike sscanf() it ignores the locale and always expects a '.' as the decimal separator.

Parameters

[in]	buf	The string containing the value
[out]	value	The double value parsed from the string.

wcsutil_str2double2()

int wcsutil_str2double2	(	const char *	buf,
		double *	value )

Translate string to doubles, ignoring the locale.

INTERNAL USE ONLY.

wcsutil_str2double2() converts a string to a pair of doubles containing the integer and fractional parts. Unlike sscanf() it ignores the locale and always expects a '.' as the decimal separator.

Parameters

[in]	buf	The string containing the value
[out]	value	parts, parsed from the string.