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