WCSLIB  7.6
wcsutil.h
Go to the documentation of this file.
1 /*============================================================================
2  WCSLIB 7.6 - an implementation of the FITS WCS standard.
3  Copyright (C) 1995-2021, 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/people/Mark.Calabretta
22  $Id: wcsutil.h,v 7.6 2021/04/13 12:57:01 mcalabre Exp $
23 *=============================================================================
24 *
25 * WCSLIB 7.6 - 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 all 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 char * String to be tested.
198 *
199 * sarr const (*char)[72]
200 * Pointer to the first element of the array.
201 *
202 * Function return value:
203 * int Status return value:
204 * 0: Not all equal.
205 * 1: All equal.
206 *
207 *
208 * wcsutil_allEq() - Test for equality of a particular vector element
209 * ------------------------------------------------------------------
210 * INTERNAL USE ONLY.
211 *
212 * wcsutil_allEq() tests for equality of a particular element in a set of
213 * vectors.
214 *
215 * Given:
216 * nvec int The number of vectors.
217 *
218 * nelem int The length of each vector.
219 *
220 * first const double*
221 * Pointer to the first element to test in the array.
222 * The elements tested for equality are
223 *
224 = *first == *(first + nelem)
225 = == *(first + nelem*2)
226 = :
227 = == *(first + nelem*(nvec-1));
228 *
229 * The array might be dimensioned as
230 *
231 = double v[nvec][nelem];
232 *
233 * Function return value:
234 * int Status return value:
235 * 0: Not all equal.
236 * 1: All equal.
237 *
238 *
239 * wcsutil_dblEq() - Test for equality of two arrays of type double
240 * ----------------------------------------------------------------
241 * INTERNAL USE ONLY.
242 *
243 * wcsutil_dblEq() tests for equality of two double-precision arrays.
244 *
245 * Given:
246 * nelem int The number of elements in each array.
247 *
248 * tol double Tolerance for comparison of the floating-point values.
249 * For example, for tol == 1e-6, all floating-point
250 * values in the arrays must be equal to the first 6
251 * decimal places. A value of 0 implies exact equality.
252 *
253 * arr1 const double*
254 * The first array.
255 *
256 * arr2 const double*
257 * The second array
258 *
259 * Function return value:
260 * int Status return value:
261 * 0: Not equal.
262 * 1: Equal.
263 *
264 *
265 * wcsutil_intEq() - Test for equality of two arrays of type int
266 * -------------------------------------------------------------
267 * INTERNAL USE ONLY.
268 *
269 * wcsutil_intEq() tests for equality of two int arrays.
270 *
271 * Given:
272 * nelem int The number of elements in each array.
273 *
274 * arr1 const int*
275 * The first array.
276 *
277 * arr2 const int*
278 * The second array
279 *
280 * Function return value:
281 * int Status return value:
282 * 0: Not equal.
283 * 1: Equal.
284 *
285 *
286 * wcsutil_strEq() - Test for equality of two string arrays
287 * --------------------------------------------------------
288 * INTERNAL USE ONLY.
289 *
290 * wcsutil_strEq() tests for equality of two string arrays.
291 *
292 * Given:
293 * nelem int The number of elements in each array.
294 *
295 * arr1 const char**
296 * The first array.
297 *
298 * arr2 const char**
299 * The second array
300 *
301 * Function return value:
302 * int Status return value:
303 * 0: Not equal.
304 * 1: Equal.
305 *
306 *
307 * wcsutil_setAll() - Set a particular vector element
308 * --------------------------------------------------
309 * INTERNAL USE ONLY.
310 *
311 * wcsutil_setAll() sets the value of a particular element in a set of vectors
312 * of type double.
313 *
314 * Given:
315 * nvec int The number of vectors.
316 *
317 * nelem int The length of each vector.
318 *
319 * Given and returned:
320 * first double* Pointer to the first element in the array, the value
321 * of which is used to set the others
322 *
323 = *(first + nelem) = *first;
324 = *(first + nelem*2) = *first;
325 = :
326 = *(first + nelem*(nvec-1)) = *first;
327 *
328 * The array might be dimensioned as
329 *
330 = double v[nvec][nelem];
331 *
332 * Function return value:
333 * void
334 *
335 *
336 * wcsutil_setAli() - Set a particular vector element
337 * --------------------------------------------------
338 * INTERNAL USE ONLY.
339 *
340 * wcsutil_setAli() sets the value of a particular element in a set of vectors
341 * of type int.
342 *
343 * Given:
344 * nvec int The number of vectors.
345 *
346 * nelem int The length of each vector.
347 *
348 * Given and returned:
349 * first int* Pointer to the first element in the array, the value
350 * of which is used to set the others
351 *
352 = *(first + nelem) = *first;
353 = *(first + nelem*2) = *first;
354 = :
355 = *(first + nelem*(nvec-1)) = *first;
356 *
357 * The array might be dimensioned as
358 *
359 = int v[nvec][nelem];
360 *
361 * Function return value:
362 * void
363 *
364 *
365 * wcsutil_setBit() - Set bits in selected elements of an array
366 * ------------------------------------------------------------
367 * INTERNAL USE ONLY.
368 *
369 * wcsutil_setBit() sets bits in selected elements of an array.
370 *
371 * Given:
372 * nelem int Number of elements in the array.
373 *
374 * sel const int*
375 * Address of a selection array of length nelem. May
376 * be specified as the null pointer in which case all
377 * elements are selected.
378 *
379 * bits int Bit mask.
380 *
381 * Given and returned:
382 * array int* Address of the array of length nelem.
383 *
384 * Function return value:
385 * void
386 *
387 *
388 * wcsutil_fptr2str() - Translate pointer-to-function to string
389 * ------------------------------------------------------------
390 * INTERNAL USE ONLY.
391 *
392 * wcsutil_fptr2str() translates a pointer-to-function to hexadecimal string
393 * representation for output. It is used by the various routines that print
394 * the contents of WCSLIB structs, noting that it is not strictly legal to
395 * type-pun a function pointer to void*. See
396 * http://stackoverflow.com/questions/2741683/how-to-format-a-function-pointer
397 *
398 * Given:
399 * fptr void(*)() Pointer to function.
400 *
401 * Returned:
402 * hext char[19] Null-terminated string. Should be at least 19 bytes
403 * in size to accomodate a 64-bit address (16 bytes in
404 * hex), plus the leading "0x" and trailing '\0'.
405 *
406 * Function return value:
407 * char * The address of hext.
408 *
409 *
410 * wcsutil_double2str() - Translate double to string ignoring the locale
411 * ---------------------------------------------------------------------
412 * INTERNAL USE ONLY.
413 *
414 * wcsutil_double2str() converts a double to a string, but unlike sprintf() it
415 * ignores the locale and always uses a '.' as the decimal separator. Also,
416 * unless it includes an exponent, the formatted value will always have a
417 * fractional part, ".0" being appended if necessary.
418 *
419 * Returned:
420 * buf char * The buffer to write the string into.
421 *
422 * Given:
423 * format char * The formatting directive, such as "%f". This
424 * may be any of the forms accepted by sprintf(), but
425 * should only include a formatting directive and
426 * nothing else. For "%g" and "%G" formats, unless it
427 * includes an exponent, the formatted value will always
428 * have a fractional part, ".0" being appended if
429 * necessary.
430 *
431 * value double The value to convert to a string.
432 *
433 *
434 * wcsutil_str2double() - Translate string to a double, ignoring the locale
435 * ------------------------------------------------------------------------
436 * INTERNAL USE ONLY.
437 *
438 * wcsutil_str2double() converts a string to a double, but unlike sscanf() it
439 * ignores the locale and always expects a '.' as the decimal separator.
440 *
441 * Given:
442 * buf char * The string containing the value
443 *
444 * Returned:
445 * value double * The double value parsed from the string.
446 *
447 *
448 * wcsutil_str2double2() - Translate string to doubles, ignoring the locale
449 * ------------------------------------------------------------------------
450 * INTERNAL USE ONLY.
451 *
452 * wcsutil_str2double2() converts a string to a pair of doubles containing the
453 * integer and fractional parts. Unlike sscanf() it ignores the locale and
454 * always expects a '.' as the decimal separator.
455 *
456 * Given:
457 * buf char * The string containing the value
458 *
459 * Returned:
460 * value double[2] The double value, split into integer and fractional
461 * parts, parsed from the string.
462 *
463 *===========================================================================*/
464 
465 #ifndef WCSLIB_WCSUTIL
466 #define WCSLIB_WCSUTIL
467 
468 #ifdef __cplusplus
469 extern "C" {
470 #endif
471 
472 void wcsdealloc(void *ptr);
473 
474 void wcsutil_strcvt(int n, char c, int nt, const char src[], char dst[]);
475 
476 void wcsutil_blank_fill(int n, char c[]);
477 void wcsutil_null_fill (int n, char c[]);
478 
479 int wcsutil_all_ival(int nelem, int ival, const int iarr[]);
480 int wcsutil_all_dval(int nelem, double dval, const double darr[]);
481 int wcsutil_all_sval(int nelem, const char *sval, const char (*sarr)[72]);
482 int wcsutil_allEq (int nvec, int nelem, const double *first);
483 
484 int wcsutil_dblEq(int nelem, double tol, const double *arr1,
485  const double *arr2);
486 int wcsutil_intEq(int nelem, const int *arr1, const int *arr2);
487 int wcsutil_strEq(int nelem, char (*arr1)[72], char (*arr2)[72]);
488 void wcsutil_setAll(int nvec, int nelem, double *first);
489 void wcsutil_setAli(int nvec, int nelem, int *first);
490 void wcsutil_setBit(int nelem, const int *sel, int bits, int *array);
491 char *wcsutil_fptr2str(void (*fptr)(void), char hext[19]);
492 void wcsutil_double2str(char *buf, const char *format, double value);
493 int wcsutil_str2double(const char *buf, double *value);
494 int wcsutil_str2double2(const char *buf, double *value);
495 
496 #ifdef __cplusplus
497 }
498 #endif
499 
500 #endif // WCSLIB_WCSUTIL
void wcsutil_setBit(int nelem, const int *sel, int bits, int *array)
Set bits in selected elements of an array.
int wcsutil_all_sval(int nelem, const char *sval, const char(*sarr)[72])
Test if all elements a string array have a given value.
void wcsutil_double2str(char *buf, const char *format, double value)
Translate double to string ignoring the locale.
void wcsutil_blank_fill(int n, char c[])
Fill a character string with blanks.
int wcsutil_allEq(int nvec, int nelem, const double *first)
Test for equality of a particular vector element.
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.
int wcsutil_str2double2(const char *buf, double *value)
Translate string to doubles, ignoring the locale.
void wcsutil_null_fill(int n, char c[])
Fill a character string with NULLs.
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_all_dval(int nelem, double dval, const double darr[])
Test if all elements a double array have a given value.
char * wcsutil_fptr2str(void(*fptr)(void), char hext[19])
Translate pointer-to-function to string.
void wcsutil_setAli(int nvec, int nelem, int *first)
Set a particular vector element.
int wcsutil_strEq(int nelem, char(*arr1)[72], char(*arr2)[72])
Test for equality of two string arrays.
int wcsutil_str2double(const char *buf, double *value)
Translate string to a double, ignoring the locale.
int wcsutil_all_ival(int nelem, int ival, const int iarr[])
Test if all elements an int array have a given value.
void wcsutil_setAll(int nvec, int nelem, double *first)
Set a particular vector element.