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