WCSLIB  7.5
wcsutil.h
Go to the documentation of this file.
1 /*============================================================================
2  WCSLIB 7.5 - 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.5 2021/03/20 05:54:58 mcalabre Exp $
23 *=============================================================================
24 *
25 * WCSLIB 7.5 - 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_allEq() - Test for equality of a particular vector element
146 * ------------------------------------------------------------------
147 * INTERNAL USE ONLY.
148 *
149 * wcsutil_allEq() tests for equality of a particular element in a set of
150 * vectors.
151 *
152 * Given:
153 * nvec int The number of vectors.
154 *
155 * nelem int The length of each vector.
156 *
157 * first const double*
158 * Pointer to the first element to test in the array.
159 * The elements tested for equality are
160 *
161 = *first == *(first + nelem)
162 = == *(first + nelem*2)
163 = :
164 = == *(first + nelem*(nvec-1));
165 *
166 * The array might be dimensioned as
167 *
168 = double v[nvec][nelem];
169 *
170 * Function return value:
171 * int Status return value:
172 * 0: Not all equal.
173 * 1: All equal.
174 *
175 *
176 * wcsutil_Eq() - Test for equality of two double arrays
177 * -----------------------------------------------------
178 * INTERNAL USE ONLY.
179 *
180 * wcsutil_Eq() tests for equality of two double-precision arrays.
181 *
182 * Given:
183 * nelem int The number of elements in each array.
184 *
185 * tol double Tolerance for comparison of the floating-point values.
186 * For example, for tol == 1e-6, all floating-point
187 * values in the arrays must be equal to the first 6
188 * decimal places. A value of 0 implies exact equality.
189 *
190 * arr1 const double*
191 * The first array.
192 *
193 * arr2 const double*
194 * The second array
195 *
196 * Function return value:
197 * int Status return value:
198 * 0: Not equal.
199 * 1: Equal.
200 *
201 *
202 * wcsutil_intEq() - Test for equality of two int arrays
203 * -----------------------------------------------------
204 * INTERNAL USE ONLY.
205 *
206 * wcsutil_intEq() tests for equality of two int arrays.
207 *
208 * Given:
209 * nelem int The number of elements in each array.
210 *
211 * arr1 const int*
212 * The first array.
213 *
214 * arr2 const int*
215 * The second array
216 *
217 * Function return value:
218 * int Status return value:
219 * 0: Not equal.
220 * 1: Equal.
221 *
222 *
223 * wcsutil_strEq() - Test for equality of two string arrays
224 * --------------------------------------------------------
225 * INTERNAL USE ONLY.
226 *
227 * wcsutil_strEq() tests for equality of two string arrays.
228 *
229 * Given:
230 * nelem int The number of elements in each array.
231 *
232 * arr1 const char**
233 * The first array.
234 *
235 * arr2 const char**
236 * The second array
237 *
238 * Function return value:
239 * int Status return value:
240 * 0: Not equal.
241 * 1: Equal.
242 *
243 *
244 * wcsutil_setAll() - Set a particular vector element
245 * --------------------------------------------------
246 * INTERNAL USE ONLY.
247 *
248 * wcsutil_setAll() sets the value of a particular element in a set of vectors.
249 *
250 * Given:
251 * nvec int The number of vectors.
252 *
253 * nelem int The length of each vector.
254 *
255 * Given and returned:
256 * first double* Pointer to the first element in the array, the value
257 * of which is used to set the others
258 *
259 = *(first + nelem) = *first;
260 = *(first + nelem*2) = *first;
261 = :
262 = *(first + nelem*(nvec-1)) = *first;
263 *
264 * The array might be dimensioned as
265 *
266 = double v[nvec][nelem];
267 *
268 * Function return value:
269 * void
270 *
271 *
272 * wcsutil_setAli() - Set a particular vector element
273 * --------------------------------------------------
274 * INTERNAL USE ONLY.
275 *
276 * wcsutil_setAli() sets the value of a particular element in a set of vectors.
277 *
278 * Given:
279 * nvec int The number of vectors.
280 *
281 * nelem int The length of each vector.
282 *
283 * Given and returned:
284 * first int* Pointer to the first element in the array, the value
285 * of which is used to set the others
286 *
287 = *(first + nelem) = *first;
288 = *(first + nelem*2) = *first;
289 = :
290 = *(first + nelem*(nvec-1)) = *first;
291 *
292 * The array might be dimensioned as
293 *
294 = int v[nvec][nelem];
295 *
296 * Function return value:
297 * void
298 *
299 *
300 * wcsutil_setBit() - Set bits in selected elements of an array
301 * ------------------------------------------------------------
302 * INTERNAL USE ONLY.
303 *
304 * wcsutil_setBit() sets bits in selected elements of an array.
305 *
306 * Given:
307 * nelem int Number of elements in the array.
308 *
309 * sel const int*
310 * Address of a selection array of length nelem. May
311 * be specified as the null pointer in which case all
312 * elements are selected.
313 *
314 * bits int Bit mask.
315 *
316 * Given and returned:
317 * array int* Address of the array of length nelem.
318 *
319 * Function return value:
320 * void
321 *
322 *
323 * wcsutil_fptr2str() - Translate pointer-to-function to string
324 * ------------------------------------------------------------
325 * INTERNAL USE ONLY.
326 *
327 * wcsutil_fptr2str() translates a pointer-to-function to hexadecimal string
328 * representation for output. It is used by the various routines that print
329 * the contents of WCSLIB structs, noting that it is not strictly legal to
330 * type-pun a function pointer to void*. See
331 * http://stackoverflow.com/questions/2741683/how-to-format-a-function-pointer
332 *
333 * Given:
334 * fptr void(*)() Pointer to function.
335 *
336 * Returned:
337 * hext char[19] Null-terminated string. Should be at least 19 bytes
338 * in size to accomodate a 64-bit address (16 bytes in
339 * hex), plus the leading "0x" and trailing '\0'.
340 *
341 * Function return value:
342 * char * The address of hext.
343 *
344 *
345 * wcsutil_double2str() - Translate double to string ignoring the locale
346 * ---------------------------------------------------------------------
347 * INTERNAL USE ONLY.
348 *
349 * wcsutil_double2str() converts a double to a string, but unlike sprintf() it
350 * ignores the locale and always uses a '.' as the decimal separator. Also,
351 * unless it includes an exponent, the formatted value will always have a
352 * fractional part, ".0" being appended if necessary.
353 *
354 * Returned:
355 * buf char * The buffer to write the string into.
356 *
357 * Given:
358 * format char * The formatting directive, such as "%f". This
359 * may be any of the forms accepted by sprintf(), but
360 * should only include a formatting directive and
361 * nothing else. For "%g" and "%G" formats, unless it
362 * includes an exponent, the formatted value will always
363 * have a fractional part, ".0" being appended if
364 * necessary.
365 *
366 * value double The value to convert to a string.
367 *
368 *
369 * wcsutil_str2double() - Translate string to a double, ignoring the locale
370 * ------------------------------------------------------------------------
371 * INTERNAL USE ONLY.
372 *
373 * wcsutil_str2double() converts a string to a double, but unlike sscanf() it
374 * ignores the locale and always expects a '.' as the decimal separator.
375 *
376 * Given:
377 * buf char * The string containing the value
378 *
379 * Returned:
380 * value double * The double value parsed from the string.
381 *
382 *
383 * wcsutil_str2double2() - Translate string to doubles, ignoring the locale
384 * ------------------------------------------------------------------------
385 * INTERNAL USE ONLY.
386 *
387 * wcsutil_str2double2() converts a string to a pair of doubles containing the
388 * integer and fractional parts. Unlike sscanf() it ignores the locale and
389 * always expects a '.' as the decimal separator.
390 *
391 * Given:
392 * buf char * The string containing the value
393 *
394 * Returned:
395 * value double[2] The double value, split into integer and fractional
396 * parts, parsed from the string.
397 *
398 *===========================================================================*/
399 
400 #ifndef WCSLIB_WCSUTIL
401 #define WCSLIB_WCSUTIL
402 
403 #ifdef __cplusplus
404 extern "C" {
405 #endif
406 
407 void wcsdealloc(void *ptr);
408 
409 void wcsutil_strcvt(int n, char c, int nt, const char src[], char dst[]);
410 
411 void wcsutil_blank_fill(int n, char c[]);
412 void wcsutil_null_fill (int n, char c[]);
413 
414 int wcsutil_allEq (int nvec, int nelem, const double *first);
415 int wcsutil_Eq(int nelem, double tol, const double *arr1,
416  const double *arr2);
417 int wcsutil_intEq(int nelem, const int *arr1, const int *arr2);
418 int wcsutil_strEq(int nelem, char (*arr1)[72], char (*arr2)[72]);
419 void wcsutil_setAll(int nvec, int nelem, double *first);
420 void wcsutil_setAli(int nvec, int nelem, int *first);
421 void wcsutil_setBit(int nelem, const int *sel, int bits, int *array);
422 char *wcsutil_fptr2str(void (*fptr)(void), char hext[19]);
423 void wcsutil_double2str(char *buf, const char *format, double value);
424 int wcsutil_str2double(const char *buf, double *value);
425 int wcsutil_str2double2(const char *buf, double *value);
426 
427 #ifdef __cplusplus
428 }
429 #endif
430 
431 #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.
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_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_setAll(int nvec, int nelem, double *first)
Set a particular vector element.