WCSLIB 8.9

Loading...
Searching...
No Matches
wcsutil.h
Go to the documentation of this file.
1/*============================================================================
2 WCSLIB 8.9 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2026, Mark Calabretta
4
5 This file is part of WCSLIB.
6
7 WCSLIB is free software: you can redistribute it and/or modify it under the
8 terms of the GNU Lesser General Public License as published by the Free
9 Software Foundation, either version 3 of the License, or (at your option)
10 any later version.
11
12 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
15 more details.
16
17 You should have received a copy of the GNU Lesser General Public License
18 along with WCSLIB. If not, see http://www.gnu.org/licenses.
19
20 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
21 http://www.atnf.csiro.au/computing/software/wcs
22 $Id: wcsutil.h,v 8.9 2026/06/18 13:00:03 mcalabre Exp $
23*=============================================================================
24*
25* WCSLIB 8.9 - C routines that implement the FITS World Coordinate System
26* (WCS) standard. Refer to the README file provided with WCSLIB for an
27* overview of the library.
28*
29*
30* Summary of the wcsutil routines
31* -------------------------------
32* Simple utility functions. With the exception of wcsdealloc(), these
33* functions are intended for internal use only by WCSLIB.
34*
35* The internal-use functions are documented here solely as an aid to
36* understanding the code. They are not intended for external use - the API
37* may change without notice!
38*
39*
40* wcsdealloc() - free memory allocated by WCSLIB functions
41* --------------------------------------------------------
42* wcsdealloc() invokes the free() system routine to free memory.
43* Specifically, it is intended to free memory allocated (using calloc()) by
44* certain WCSLIB functions (e.g. wcshdo(), wcsfixi(), fitshdr()), which it is
45* the user's responsibility to deallocate.
46*
47* In certain situations, for example multithreading, it may be important that
48* this be done within the WCSLIB sharable library's runtime environment.
49*
50* PLEASE NOTE: wcsdealloc() must not be used in place of the destructors for
51* particular structs, such as wcsfree(), celfree(), etc.
52*
53* Given and returned:
54* ptr void* Address of the allocated memory.
55*
56* Function return value:
57* void
58*
59*
60* wcsutil_strcvt() - Copy character string with padding
61* -----------------------------------------------------
62* INTERNAL USE ONLY.
63*
64* wcsutil_strcvt() copies one character string to another up to the specified
65* maximum number of characters.
66*
67* If the given string is null-terminated, then the NULL character copied to
68* the returned string, and all characters following it up to the specified
69* maximum, are replaced with the specified substitute character, either blank
70* or NULL.
71*
72* If the source string is not null-terminated and the substitute character is
73* blank, then copy the maximum number of characters and do nothing further.
74* However, if the substitute character is NULL, then the last character and
75* all consecutive blank characters preceding it will be replaced with NULLs.
76*
77* Used by the Fortran wrapper functions in translating C strings into Fortran
78* CHARACTER variables and vice versa.
79*
80* Given:
81* n int Maximum number of characters to copy.
82*
83* c char Substitute character, either NULL or blank (anything
84* other than NULL).
85*
86* nt int If true, then dst is of length n+1, with the last
87* character always set to NULL.
88*
89* src char[] Character string to be copied. If null-terminated,
90* then need not be of length n, otherwise it must be.
91*
92* Returned:
93* dst char[] Destination character string, which must be long
94* enough to hold n characters. Note that this string
95* will not be null-terminated if the substitute
96* character is blank.
97*
98* Function return value:
99* void
100*
101*
102* wcsutil_blank_fill() - Fill a character string with blanks
103* ----------------------------------------------------------
104* INTERNAL USE ONLY.
105*
106* wcsutil_blank_fill() pads a character sub-string with blanks starting with
107* the terminating NULL character (if any).
108*
109* Given:
110* n int Length of the sub-string.
111*
112* Given and returned:
113* c char[] The character sub-string, which will not be
114* null-terminated on return.
115*
116* Function return value:
117* void
118*
119*
120* wcsutil_null_fill() - Fill a character string with NULLs
121* --------------------------------------------------------
122* INTERNAL USE ONLY.
123*
124* wcsutil_null_fill() strips trailing blanks from a string (or sub-string) and
125* propagates the terminating NULL character (if any) to the end of the string.
126*
127* If the string is not null-terminated, then the last character and all
128* consecutive blank characters preceding it will be replaced with NULLs.
129*
130* Mainly used in the C library to strip trailing blanks from FITS keyvalues.
131* Also used to make character strings intelligible in the GNU debugger, which
132* prints the rubbish following the terminating NULL character, thereby
133* obscuring the valid part of the string.
134*
135* Given:
136* n int Number of characters.
137*
138* Given and returned:
139* c char[] The character (sub-)string.
140*
141* Function return value:
142* void
143*
144*
145* wcsutil_all_ival() - Test if all elements an int array have a given value
146* -------------------------------------------------------------------------
147* INTERNAL USE ONLY.
148*
149* wcsutil_all_ival() tests whether all elements of an array of type int all
150* have the specified value.
151*
152* Given:
153* nelem int The length of the array.
154*
155* ival int Value to be tested.
156*
157* iarr const int[]
158* Pointer to the first element of the array.
159*
160* Function return value:
161* int Status return value:
162* 0: Not all equal.
163* 1: All equal.
164*
165*
166* wcsutil_all_dval() - Test if all elements a double array have a given value
167* ---------------------------------------------------------------------------
168* INTERNAL USE ONLY.
169*
170* wcsutil_all_dval() tests whether all elements of an array of type double all
171* have the specified value.
172*
173* Given:
174* nelem int The length of the array.
175*
176* dval int Value to be tested.
177*
178* darr const double[]
179* Pointer to the first element of the array.
180*
181* Function return value:
182* int Status return value:
183* 0: Not all equal.
184* 1: All equal.
185*
186*
187* wcsutil_all_sval() - Test if all elements a string array have a given value
188* ---------------------------------------------------------------------------
189* INTERNAL USE ONLY.
190*
191* wcsutil_all_sval() tests whether the elements of an array of type
192* char (*)[72] all have the specified value.
193*
194* Given:
195* nelem int The length of the array.
196*
197* sval const char *
198* String to be tested.
199*
200* sarr const char (*)[72]
201* Pointer to the first element of the array.
202*
203* Function return value:
204* int Status return value:
205* 0: Not all equal.
206* 1: All equal.
207*
208*
209* wcsutil_allEq() - Test for equality of a particular vector element
210* ------------------------------------------------------------------
211* INTERNAL USE ONLY.
212*
213* wcsutil_allEq() tests for equality of a particular element in a set of
214* vectors.
215*
216* Given:
217* nvec int The number of vectors.
218*
219* nelem int The length of each vector.
220*
221* first const double*
222* Pointer to the first element to test in the array.
223* The elements tested for equality are
224*
225= *first == *(first + nelem)
226= == *(first + nelem*2)
227= :
228= == *(first + nelem*(nvec-1));
229*
230* The array might be dimensioned as
231*
232= double v[nvec][nelem];
233*
234* Function return value:
235* int Status return value:
236* 0: Not all equal.
237* 1: All equal.
238*
239*
240* wcsutil_dblEq() - Test for equality of two arrays of type double
241* ----------------------------------------------------------------
242* INTERNAL USE ONLY.
243*
244* wcsutil_dblEq() tests for equality of two double-precision arrays.
245*
246* Given:
247* nelem int The number of elements in each array.
248*
249* tol double Tolerance for comparison of the floating-point values.
250* For example, for tol == 1e-6, all floating-point
251* values in the arrays must be equal to the first 6
252* decimal places. A value of 0 implies exact equality.
253*
254* arr1 const double*
255* The first array.
256*
257* arr2 const double*
258* The second array
259*
260* Function return value:
261* int Status return value:
262* 0: Not equal.
263* 1: Equal.
264*
265*
266* wcsutil_intEq() - Test for equality of two arrays of type int
267* -------------------------------------------------------------
268* INTERNAL USE ONLY.
269*
270* wcsutil_intEq() tests for equality of two int arrays.
271*
272* Given:
273* nelem int The number of elements in each array.
274*
275* arr1 const int*
276* The first array.
277*
278* arr2 const int*
279* The second array
280*
281* Function return value:
282* int Status return value:
283* 0: Not equal.
284* 1: Equal.
285*
286*
287* wcsutil_strEq() - Test for equality of two string arrays
288* --------------------------------------------------------
289* INTERNAL USE ONLY.
290*
291* wcsutil_strEq() tests for equality of two string arrays.
292*
293* Given:
294* nelem int The number of elements in each array.
295*
296* arr1 const char**
297* The first array.
298*
299* arr2 const char**
300* The second array
301*
302* Function return value:
303* int Status return value:
304* 0: Not equal.
305* 1: Equal.
306*
307*
308* wcsutil_setAll() - Set a particular vector element
309* --------------------------------------------------
310* INTERNAL USE ONLY.
311*
312* wcsutil_setAll() sets the value of a particular element in a set of vectors
313* of type double.
314*
315* Given:
316* nvec int The number of vectors.
317*
318* nelem int The length of each vector.
319*
320* Given and returned:
321* first double* Pointer to the first element in the array, the value
322* of which is used to set the others
323*
324= *(first + nelem) = *first;
325= *(first + nelem*2) = *first;
326= :
327= *(first + nelem*(nvec-1)) = *first;
328*
329* The array might be dimensioned as
330*
331= double v[nvec][nelem];
332*
333* Function return value:
334* void
335*
336*
337* wcsutil_setAli() - Set a particular vector element
338* --------------------------------------------------
339* INTERNAL USE ONLY.
340*
341* wcsutil_setAli() sets the value of a particular element in a set of vectors
342* of type int.
343*
344* Given:
345* nvec int The number of vectors.
346*
347* nelem int The length of each vector.
348*
349* Given and returned:
350* first int* Pointer to the first element in the array, the value
351* of which is used to set the others
352*
353= *(first + nelem) = *first;
354= *(first + nelem*2) = *first;
355= :
356= *(first + nelem*(nvec-1)) = *first;
357*
358* The array might be dimensioned as
359*
360= int v[nvec][nelem];
361*
362* Function return value:
363* void
364*
365*
366* wcsutil_setBit() - Set bits in selected elements of an array
367* ------------------------------------------------------------
368* INTERNAL USE ONLY.
369*
370* wcsutil_setBit() sets bits in selected elements of an array.
371*
372* Given:
373* nelem int Number of elements in the array.
374*
375* sel const int*
376* Address of a selection array of length nelem. May
377* be specified as the null pointer in which case all
378* elements are selected.
379*
380* bits int Bit mask.
381*
382* Given and returned:
383* array int* Address of the array of length nelem.
384*
385* Function return value:
386* void
387*
388*
389* wcsutil_fptr2str() - Translate pointer-to-function to string
390* ------------------------------------------------------------
391* INTERNAL USE ONLY.
392*
393* wcsutil_fptr2str() translates a pointer-to-function to hexadecimal string
394* representation for output. It is used by the various routines that print
395* the contents of WCSLIB structs, noting that it is not strictly legal to
396* type-pun a function pointer to void*. See
397* http://stackoverflow.com/questions/2741683/how-to-format-a-function-pointer
398*
399* Given:
400* fptr void(*)() Pointer to function.
401*
402* Returned:
403* hext char[19] Null-terminated string. Should be at least 19 bytes
404* in size to accomodate a 64-bit address (16 bytes in
405* hex), plus the leading "0x" and trailing '\0'.
406*
407* Function return value:
408* char * The address of hext.
409*
410*
411* wcsutil_double2str() - Translate double to string ignoring the locale
412* ---------------------------------------------------------------------
413* INTERNAL USE ONLY.
414*
415* wcsutil_double2str() converts a double to a string, but unlike sprintf() it
416* ignores the locale and always uses a '.' as the decimal separator. Also,
417* unless it includes an exponent, the formatted value will always have a
418* fractional part, ".0" being appended if necessary.
419*
420* Returned:
421* buf char * The buffer to write the string into.
422*
423* Given:
424* size size_t Length of buf.
425*
426* format char * The formatting directive, such as "%f". This
427* may be any of the forms accepted by sprintf(), but
428* should only include a formatting directive and
429* nothing else. For "%g" and "%G" formats, unless it
430* includes an exponent, the formatted value will always
431* have a fractional part, ".0" being appended if
432* necessary.
433*
434* value double The value to convert to a string.
435*
436*
437* wcsutil_str2double() - Translate string to a double, ignoring the locale
438* ------------------------------------------------------------------------
439* INTERNAL USE ONLY.
440*
441* wcsutil_str2double() converts a string to a double, but unlike sscanf() it
442* ignores the locale and always expects a '.' as the decimal separator.
443*
444* Given:
445* buf char * The string containing the value
446*
447* Returned:
448* value double * The double value parsed from the string.
449*
450*
451* wcsutil_str2double2() - Translate string to doubles, ignoring the locale
452* ------------------------------------------------------------------------
453* INTERNAL USE ONLY.
454*
455* wcsutil_str2double2() converts a string to a pair of doubles containing the
456* integer and fractional parts. Unlike sscanf() it ignores the locale and
457* always expects a '.' as the decimal separator.
458*
459* Given:
460* buf char * The string containing the value
461*
462* Returned:
463* value double[2] The double value, split into integer and fractional
464* parts, parsed from the string.
465*
466*===========================================================================*/
467
468#ifndef WCSLIB_WCSUTIL
469#define WCSLIB_WCSUTIL
470
471#ifdef __cplusplus
472 extern "C" {
473#endif
474
475 void wcsdealloc(void *ptr);
476
477 void wcsutil_strcvt(int n, char c, int nt, const char src[], char dst[]);
478
479 void wcsutil_blank_fill(int n, char c[]);
480 void wcsutil_null_fill (int n, char c[]);
481
482 int wcsutil_all_ival(int nelem, int ival, const int iarr[]);
483 int wcsutil_all_dval(int nelem, double dval, const double darr[]);
484 int wcsutil_all_sval(int nelem, const char *sval, const char (*sarr)[72]);
485 int wcsutil_allEq (int nvec, int nelem, const double *first);
486
487 int wcsutil_dblEq(int nelem, double tol, const double *arr1,
488 const double *arr2);
489 int wcsutil_intEq(int nelem, const int *arr1, const int *arr2);
490 int wcsutil_strEq(int nelem, char (*arr1)[72], char (*arr2)[72]);
491 void wcsutil_setAll(int nvec, int nelem, double *first);
492 void wcsutil_setAli(int nvec, int nelem, int *first);
493 void wcsutil_setBit(int nelem, const int *sel, int bits, int *array);
494 char *wcsutil_fptr2str(void (*fptr)(void), char hext[19]);
495 void wcsutil_double2str(char *buf, size_t bsize, const char *format,
496 double value);
497 int wcsutil_str2double(const char *buf, double *value);
498 int wcsutil_str2double2(const char *buf, double *value);
499
500#ifdef __cplusplus
501}
502#endif
503
504#endif // WCSLIB_WCSUTIL
wcsutil_setBit
void wcsutil_setBit(int nelem, const int *sel, int bits, int *array)
Set bits in selected elements of an array.
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.
wcsutil_blank_fill
void wcsutil_blank_fill(int n, char c[])
Fill a character string with blanks.
wcsutil_allEq
int wcsutil_allEq(int nvec, int nelem, const double *first)
Test for equality of a particular vector element.
wcsdealloc
void wcsdealloc(void *ptr)
free memory allocated by WCSLIB functions.
wcsutil_double2str
void wcsutil_double2str(char *buf, size_t bsize, const char *format, double value)
Translate double to string ignoring the locale.
wcsutil_strcvt
void wcsutil_strcvt(int n, char c, int nt, const char src[], char dst[])
Copy character string with padding.
wcsutil_str2double2
int wcsutil_str2double2(const char *buf, double *value)
Translate string to doubles, ignoring the locale.
wcsutil_null_fill
void wcsutil_null_fill(int n, char c[])
Fill a character string with NULLs.
wcsutil_dblEq
int wcsutil_dblEq(int nelem, double tol, const double *arr1, const double *arr2)
Test for equality of two arrays of type double.
wcsutil_intEq
int wcsutil_intEq(int nelem, const int *arr1, const int *arr2)
Test for equality of two arrays of type int.
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.
wcsutil_fptr2str
char * wcsutil_fptr2str(void(*fptr)(void), char hext[19])
Translate pointer-to-function to string.
wcsutil_setAli
void wcsutil_setAli(int nvec, int nelem, int *first)
Set a particular vector element.
wcsutil_strEq
int wcsutil_strEq(int nelem, char(*arr1)[72], char(*arr2)[72])
Test for equality of two string arrays.
wcsutil_str2double
int wcsutil_str2double(const char *buf, double *value)
Translate string to a double, ignoring the locale.
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.
wcsutil_setAll
void wcsutil_setAll(int nvec, int nelem, double *first)
Set a particular vector element.