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