WCSLIB  7.4
wcsutil.h
Go to the documentation of this file.
1 /*============================================================================
2  WCSLIB 7.4 - 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.4 2021/01/31 02:24:51 mcalabre Exp $
23 *=============================================================================
24 *
25 * WCSLIB 7.4 - 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 terminating NULL character,
68 * and all characters following it up to the specified maximum, are replaced
69 * with the specified substitute character, either blank or NULL.
70 *
71 * If the source string is not null-terminated and the substitute character is
72 * blank, then copy the maximum number of characters and do nothing further.
73 * However, if the substitute character is NULL, then the last character and
74 * all consecutive blank characters preceding it will be replaced with NULLs.
75 *
76 * Used by the Fortran wrapper functions in translating C strings into Fortran
77 * CHARACTER variables and vice versa.
78 *
79 * Given:
80 * n int Maximum number of characters to copy.
81 *
82 * c char Substitute character, either NULL or blank (anything
83 * other than NULL).
84 *
85 * src const char[]
86 * Character string to be copied. Need not be
87 * null-terminated.
88 *
89 * Returned:
90 * dst char[] Destination character string, which must be long
91 * enough to hold n characters. Note that this string
92 * will not be null-terminated if the substitute
93 * character is blank.
94 *
95 * Function return value:
96 * void
97 *
98 *
99 * wcsutil_blank_fill() - Fill a character string with blanks
100 * ----------------------------------------------------------
101 * INTERNAL USE ONLY.
102 *
103 * wcsutil_blank_fill() pads a character sub-string with blanks starting with
104 * the terminating NULL character (if any).
105 *
106 * Given:
107 * n int Length of the sub-string.
108 *
109 * Given and returned:
110 * c char[] The character sub-string, which will not be
111 * null-terminated on return.
112 *
113 * Function return value:
114 * void
115 *
116 *
117 * wcsutil_null_fill() - Fill a character string with NULLs
118 * --------------------------------------------------------
119 * INTERNAL USE ONLY.
120 *
121 * wcsutil_null_fill() strips trailing blanks from a string (or sub-string) and
122 * propagates the terminating NULL character (if any) to the end of the string.
123 *
124 * If the string is not null-terminated, then the last character and all
125 * consecutive blank characters preceding it will be replaced with NULLs.
126 *
127 * Mainly used in the C library to strip trailing blanks from FITS keyvalues.
128 * Also used to make character strings intelligible in the GNU debugger, which
129 * prints the rubbish following the terminating NULL character, thereby
130 * obscuring the valid part of the string.
131 *
132 * Given:
133 * n int Number of characters.
134 *
135 * Given and returned:
136 * c char[] The character (sub-)string.
137 *
138 * Function return value:
139 * void
140 *
141 *
142 * wcsutil_allEq() - Test for equality of a particular vector element
143 * ------------------------------------------------------------------
144 * INTERNAL USE ONLY.
145 *
146 * wcsutil_allEq() tests for equality of a particular element in a set of
147 * vectors.
148 *
149 * Given:
150 * nvec int The number of vectors.
151 *
152 * nelem int The length of each vector.
153 *
154 * first const double*
155 * Pointer to the first element to test in the array.
156 * The elements tested for equality are
157 *
158 = *first == *(first + nelem)
159 = == *(first + nelem*2)
160 = :
161 = == *(first + nelem*(nvec-1));
162 *
163 * The array might be dimensioned as
164 *
165 = double v[nvec][nelem];
166 *
167 * Function return value:
168 * int Status return value:
169 * 0: Not all equal.
170 * 1: All equal.
171 *
172 *
173 * wcsutil_Eq() - Test for equality of two double arrays
174 * -----------------------------------------------------
175 * INTERNAL USE ONLY.
176 *
177 * wcsutil_Eq() tests for equality of two double-precision arrays.
178 *
179 * Given:
180 * nelem int The number of elements in each array.
181 *
182 * tol double Tolerance for comparison of the floating-point values.
183 * For example, for tol == 1e-6, all floating-point
184 * values in the arrays must be equal to the first 6
185 * decimal places. A value of 0 implies exact equality.
186 *
187 * arr1 const double*
188 * The first array.
189 *
190 * arr2 const double*
191 * The second array
192 *
193 * Function return value:
194 * int Status return value:
195 * 0: Not equal.
196 * 1: Equal.
197 *
198 *
199 * wcsutil_intEq() - Test for equality of two int arrays
200 * -----------------------------------------------------
201 * INTERNAL USE ONLY.
202 *
203 * wcsutil_intEq() tests for equality of two int arrays.
204 *
205 * Given:
206 * nelem int The number of elements in each array.
207 *
208 * arr1 const int*
209 * The first array.
210 *
211 * arr2 const int*
212 * The second array
213 *
214 * Function return value:
215 * int Status return value:
216 * 0: Not equal.
217 * 1: Equal.
218 *
219 *
220 * wcsutil_strEq() - Test for equality of two string arrays
221 * --------------------------------------------------------
222 * INTERNAL USE ONLY.
223 *
224 * wcsutil_strEq() tests for equality of two string arrays.
225 *
226 * Given:
227 * nelem int The number of elements in each array.
228 *
229 * arr1 const char**
230 * The first array.
231 *
232 * arr2 const char**
233 * The second array
234 *
235 * Function return value:
236 * int Status return value:
237 * 0: Not equal.
238 * 1: Equal.
239 *
240 *
241 * wcsutil_setAll() - Set a particular vector element
242 * --------------------------------------------------
243 * INTERNAL USE ONLY.
244 *
245 * wcsutil_setAll() sets the value of a particular element in a set of vectors.
246 *
247 * Given:
248 * nvec int The number of vectors.
249 *
250 * nelem int The length of each vector.
251 *
252 * Given and returned:
253 * first double* Pointer to the first element in the array, the value
254 * of which is used to set the others
255 *
256 = *(first + nelem) = *first;
257 = *(first + nelem*2) = *first;
258 = :
259 = *(first + nelem*(nvec-1)) = *first;
260 *
261 * The array might be dimensioned as
262 *
263 = double v[nvec][nelem];
264 *
265 * Function return value:
266 * void
267 *
268 *
269 * wcsutil_setAli() - Set a particular vector element
270 * --------------------------------------------------
271 * INTERNAL USE ONLY.
272 *
273 * wcsutil_setAli() sets the value of a particular element in a set of vectors.
274 *
275 * Given:
276 * nvec int The number of vectors.
277 *
278 * nelem int The length of each vector.
279 *
280 * Given and returned:
281 * first int* Pointer to the first element in the array, the value
282 * of which is used to set the others
283 *
284 = *(first + nelem) = *first;
285 = *(first + nelem*2) = *first;
286 = :
287 = *(first + nelem*(nvec-1)) = *first;
288 *
289 * The array might be dimensioned as
290 *
291 = int v[nvec][nelem];
292 *
293 * Function return value:
294 * void
295 *
296 *
297 * wcsutil_setBit() - Set bits in selected elements of an array
298 * ------------------------------------------------------------
299 * INTERNAL USE ONLY.
300 *
301 * wcsutil_setBit() sets bits in selected elements of an array.
302 *
303 * Given:
304 * nelem int Number of elements in the array.
305 *
306 * sel const int*
307 * Address of a selection array of length nelem. May
308 * be specified as the null pointer in which case all
309 * elements are selected.
310 *
311 * bits int Bit mask.
312 *
313 * Given and returned:
314 * array int* Address of the array of length nelem.
315 *
316 * Function return value:
317 * void
318 *
319 *
320 * wcsutil_fptr2str() - Translate pointer-to-function to string
321 * ------------------------------------------------------------
322 * INTERNAL USE ONLY.
323 *
324 * wcsutil_fptr2str() translates a pointer-to-function to hexadecimal string
325 * representation for output. It is used by the various routines that print
326 * the contents of WCSLIB structs, noting that it is not strictly legal to
327 * type-pun a function pointer to void*. See
328 * http://stackoverflow.com/questions/2741683/how-to-format-a-function-pointer
329 *
330 * Given:
331 * fptr void(*)() Pointer to function.
332 *
333 * Returned:
334 * hext char[19] Null-terminated string. Should be at least 19 bytes
335 * in size to accomodate a 64-bit address (16 bytes in
336 * hex), plus the leading "0x" and trailing '\0'.
337 *
338 * Function return value:
339 * char * The address of hext.
340 *
341 *
342 * wcsutil_double2str() - Translate double to string ignoring the locale
343 * ---------------------------------------------------------------------
344 * INTERNAL USE ONLY.
345 *
346 * wcsutil_double2str() converts a double to a string, but unlike sprintf() it
347 * ignores the locale and always uses a '.' as the decimal separator. Also,
348 * unless it includes an exponent, the formatted value will always have a
349 * fractional part, ".0" being appended if necessary.
350 *
351 * Returned:
352 * buf char * The buffer to write the string into.
353 *
354 * Given:
355 * format char * The formatting directive, such as "%f". This
356 * may be any of the forms accepted by sprintf(), but
357 * should only include a formatting directive and
358 * nothing else. For "%g" and "%G" formats, unless it
359 * includes an exponent, the formatted value will always
360 * have a fractional part, ".0" being appended if
361 * necessary.
362 *
363 * value double The value to convert to a string.
364 *
365 *
366 * wcsutil_str2double() - Translate string to a double, ignoring the locale
367 * ------------------------------------------------------------------------
368 * INTERNAL USE ONLY.
369 *
370 * wcsutil_str2double() converts a string to a double, but unlike sscanf() it
371 * ignores the locale and always expects a '.' as the decimal separator.
372 *
373 * Given:
374 * buf char * The string containing the value
375 *
376 * Returned:
377 * value double * The double value parsed from the string.
378 *
379 *
380 * wcsutil_str2double2() - Translate string to doubles, ignoring the locale
381 * ------------------------------------------------------------------------
382 * INTERNAL USE ONLY.
383 *
384 * wcsutil_str2double2() converts a string to a pair of doubles containing the
385 * integer and fractional parts. Unlike sscanf() it ignores the locale and
386 * always expects a '.' as the decimal separator.
387 *
388 * Given:
389 * buf char * The string containing the value
390 *
391 * Returned:
392 * value double[2] The double value, split into integer and fractional
393 * parts, parsed from the string.
394 *
395 *===========================================================================*/
396 
397 #ifndef WCSLIB_WCSUTIL
398 #define WCSLIB_WCSUTIL
399 
400 #ifdef __cplusplus
401 extern "C" {
402 #endif
403 
404 void wcsdealloc(void *ptr);
405 
406 void wcsutil_strcvt(int n, char c, const char src[], char dst[]);
407 
408 void wcsutil_blank_fill(int n, char c[]);
409 void wcsutil_null_fill (int n, char c[]);
410 
411 int wcsutil_allEq (int nvec, int nelem, const double *first);
412 int wcsutil_Eq(int nelem, double tol, const double *arr1,
413  const double *arr2);
414 int wcsutil_intEq(int nelem, const int *arr1, const int *arr2);
415 int wcsutil_strEq(int nelem, char (*arr1)[72], char (*arr2)[72]);
416 void wcsutil_setAll(int nvec, int nelem, double *first);
417 void wcsutil_setAli(int nvec, int nelem, int *first);
418 void wcsutil_setBit(int nelem, const int *sel, int bits, int *array);
419 char *wcsutil_fptr2str(void (*fptr)(void), char hext[19]);
420 void wcsutil_double2str(char *buf, const char *format, double value);
421 int wcsutil_str2double(const char *buf, double *value);
422 int wcsutil_str2double2(const char *buf, double *value);
423 
424 #ifdef __cplusplus
425 }
426 #endif
427 
428 #endif // WCSLIB_WCSUTIL
void wcsutil_setBit(int nelem, const int *sel, int bits, int *array)
Set bits in selected elements of an array.
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.
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_intEq(int nelem, const int *arr1, const int *arr2)
Test for equality of two int arrays.
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_Eq(int nelem, double tol, const double *arr1, const double *arr2)
Test for equality of two double arrays.
void wcsutil_strcvt(int n, char c, const char src[], char dst[])
Copy character string with padding.
void wcsutil_setAll(int nvec, int nelem, double *first)
Set a particular vector element.