WCSLIB 6.2

wcsutil.h
Go to the documentation of this file.
1 /*============================================================================
2
3 WCSLIB 6.2 - an implementation of the FITS WCS standard.
4 Copyright (C) 1995-2018, 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.2 2018/10/20 10:03:13 mcalabre Exp $
26 *=============================================================================
27 *
28 * WCSLIB 6.2 - 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 for internal use only by WCSLIB. They are
36 * documented here solely as an aid to understanding the code. They are not
37 * intended for external use - the API may change without notice!
38 *
39 *
40 * wcsutil_blank_fill() - Fill a character string with blanks
41 * ----------------------------------------------------------
42 * INTERNAL USE ONLY.
43 *
44 * wcsutil_blank_fill() pads a character string with blanks starting with the
45 * terminating NULL character.
46 *
47 * Used by the Fortran wrapper functions in translating C character strings
48 * into Fortran CHARACTER variables.
49 *
50 * Given:
51 * n int Length of the character array, c[].
52 *
53 * Given and returned:
54 * c char[] The character string. It will not be null-terminated
55 * on return.
56 *
57 * Function return value:
58 * void
59 *
60 *
61 * wcsutil_null_fill() - Fill a character string with NULLs
62 * --------------------------------------------------------
63 * INTERNAL USE ONLY.
64 *
65 * wcsutil_null_fill() strips off trailing blanks and pads the character array
66 * holding the string with NULL characters.
67 *
68 * Used mainly to make character strings intelligible in the GNU debugger which
69 * prints the rubbish following the terminating NULL, obscuring the valid part
70 * of the string.
71 *
72 * Given:
73 * n int Number of characters.
74 *
75 * Given and returned:
76 * c char[] The character string.
77 *
78 * Function return value:
79 * void
80 *
81 *
82 * wcsutil_allEq() - Test for equality of a particular vector element
83 * ------------------------------------------------------------------
84 * INTERNAL USE ONLY.
85 *
86 * wcsutil_allEq() tests for equality of a particular element in a set of
87 * vectors.
88 *
89 * Given:
90 * nvec int The number of vectors.
91 *
92 * nelem int The length of each vector.
93 *
94 * first const double*
95 * Pointer to the first element to test in the array.
96 * The elements tested for equality are
97 *
98 = *first == *(first + nelem)
99 = == *(first + nelem*2)
100 = :
101 = == *(first + nelem*(nvec-1));
102 *
103 * The array might be dimensioned as
104 *
105 = double v[nvec][nelem];
106 *
107 * Function return value:
108 * int Status return value:
109 * 0: Not all equal.
110 * 1: All equal.
111 *
112 *
113 * wcsutil_Eq() - Test for equality of two double arrays
114 * -----------------------------------------------------
115 * INTERNAL USE ONLY.
116 *
117 * wcsutil_Eq() tests for equality of two double-precision arrays.
118 *
119 * Given:
120 * nelem int The number of elements in each array.
121 *
122 * tol double Tolerance for comparison of the floating-point values.
123 * For example, for tol == 1e-6, all floating-point
124 * values in the arrays must be equal to the first 6
125 * decimal places. A value of 0 implies exact equality.
126 *
127 * arr1 const double*
128 * The first array.
129 *
130 * arr2 const double*
131 * The second array
132 *
133 * Function return value:
134 * int Status return value:
135 * 0: Not equal.
136 * 1: Equal.
137 *
138 *
139 * wcsutil_intEq() - Test for equality of two int arrays
140 * -----------------------------------------------------
141 * INTERNAL USE ONLY.
142 *
143 * wcsutil_intEq() tests for equality of two int arrays.
144 *
145 * Given:
146 * nelem int The number of elements in each array.
147 *
148 * arr1 const int*
149 * The first array.
150 *
151 * arr2 const int*
152 * The second array
153 *
154 * Function return value:
155 * int Status return value:
156 * 0: Not equal.
157 * 1: Equal.
158 *
159 *
160 * wcsutil_strEq() - Test for equality of two string arrays
161 * --------------------------------------------------------
162 * INTERNAL USE ONLY.
163 *
164 * wcsutil_strEq() tests for equality of two string arrays.
165 *
166 * Given:
167 * nelem int The number of elements in each array.
168 *
169 * arr1 const char**
170 * The first array.
171 *
172 * arr2 const char**
173 * The second array
174 *
175 * Function return value:
176 * int Status return value:
177 * 0: Not equal.
178 * 1: Equal.
179 *
180 *
181 * wcsutil_setAll() - Set a particular vector element
182 * --------------------------------------------------
183 * INTERNAL USE ONLY.
184 *
185 * wcsutil_setAll() sets the value of a particular element in a set of vectors.
186 *
187 * Given:
188 * nvec int The number of vectors.
189 *
190 * nelem int The length of each vector.
191 *
192 * Given and returned:
193 * first double* Pointer to the first element in the array, the value
194 * of which is used to set the others
195 *
196 = *(first + nelem) = *first;
197 = *(first + nelem*2) = *first;
198 = :
199 = *(first + nelem*(nvec-1)) = *first;
200 *
201 * The array might be dimensioned as
202 *
203 = double v[nvec][nelem];
204 *
205 * Function return value:
206 * void
207 *
208 *
209 * wcsutil_setAli() - Set a particular vector element
210 * --------------------------------------------------
211 * INTERNAL USE ONLY.
212 *
213 * wcsutil_setAli() sets the value of a particular element in a set of vectors.
214 *
215 * Given:
216 * nvec int The number of vectors.
217 *
218 * nelem int The length of each vector.
219 *
220 * Given and returned:
221 * first int* Pointer to the first element in the array, the value
222 * of which is used to set the others
223 *
224 = *(first + nelem) = *first;
225 = *(first + nelem*2) = *first;
226 = :
227 = *(first + nelem*(nvec-1)) = *first;
228 *
229 * The array might be dimensioned as
230 *
231 = int v[nvec][nelem];
232 *
233 * Function return value:
234 * void
235 *
236 *
237 * wcsutil_setBit() - Set bits in selected elements of an array
238 * ------------------------------------------------------------
239 * INTERNAL USE ONLY.
240 *
241 * wcsutil_setBit() sets bits in selected elements of an array.
242 *
243 * Given:
244 * nelem int Number of elements in the array.
245 *
246 * sel const int*
247 * Address of a selection array of length nelem. May
248 * be specified as the null pointer in which case all
249 * elements are selected.
250 *
251 * bits int Bit mask.
252 *
253 * Given and returned:
254 * array int* Address of the array of length nelem.
255 *
256 * Function return value:
257 * void
258 *
259 *
260 * wcsutil_fptr2str() - Translate pointer-to-function to string
261 * ------------------------------------------------------------
262 * INTERNAL USE ONLY.
263 *
264 * wcsutil_fptr2str() translates a pointer-to-function to hexadecimal string
265 * representation for output. It is used by the various routines that print
266 * the contents of WCSLIB structs, noting that it is not strictly legal to
267 * type-pun a function pointer to void*. See
268 * http://stackoverflow.com/questions/2741683/how-to-format-a-function-pointer
269 *
270 * Given:
271 * fptr void(*)() Pointer to function.
272 *
273 * Returned:
274 * hext char[19] Null-terminated string. Should be at least 19 bytes
275 * in size to accomodate a 64-bit address (16 bytes in
276 * hex), plus the leading "0x" and trailing '\0'.
277 *
278 * Function return value:
279 * char * The address of hext.
280 *
281 *
282 * wcsutil_double2str() - Translate double to string ignoring the locale
283 * ---------------------------------------------------------------------
284 * INTERNAL USE ONLY.
285 *
286 * wcsutil_double2str() converts a double to a string, but unlike sprintf() it
287 * ignores the locale and always uses a '.' as the decimal separator. Also,
288 * unless it includes an exponent, the formatted value will always have a
289 * fractional part, ".0" being appended if necessary.
290 *
291 * Returned:
292 * buf char * The buffer to write the string into.
293 *
294 * Given:
295 * format char * The formatting directive, such as "%f". This
296 * may be any of the forms accepted by sprintf(), but
297 * should only include a formatting directive and
298 * nothing else. For "%g" and "%G" formats, unless it
299 * includes an exponent, the formatted value will always
300 * have a fractional part, ".0" being appended if
301 * necessary.
302 *
303 * value double The value to convert to a string.
304 *
305 *
306 * wcsutil_str2double() - Translate string to a double, ignoring the locale
307 * ------------------------------------------------------------------------
308 * INTERNAL USE ONLY.
309 *
310 * wcsutil_str2double() converts a string to a double, but unlike sscanf() it
311 * ignores the locale and always expects a '.' as the decimal separator.
312 *
313 * Given:
314 * buf char * The string containing the value
315 *
316 * Returned:
317 * value double * The double value parsed from the string.
318 *
319 *
320 * wcsutil_str2double2() - Translate string to doubles, ignoring the locale
321 * ------------------------------------------------------------------------
322 * INTERNAL USE ONLY.
323 *
324 * wcsutil_str2double2() converts a string to a pair of doubles containing the
325 * integer and fractional parts. Unlike sscanf() it ignores the locale and
326 * always expects a '.' as the decimal separator.
327 *
328 * Given:
329 * buf char * The string containing the value
330 *
331 * Returned:
332 * value double[2] The double value, split into integer and fractional
333 * parts, parsed from the string.
334 *
335 *===========================================================================*/
336
337 #ifndef WCSLIB_WCSUTIL
338 #define WCSLIB_WCSUTIL
339
340 #ifdef __cplusplus
341 extern "C" {
342 #endif
343
344 void wcsutil_blank_fill(int n, char c[]);
345 void wcsutil_null_fill (int n, char c[]);
346
347 int wcsutil_allEq (int nvec, int nelem, const double *first);
348 int wcsutil_Eq(int nelem, double tol, const double *arr1,
349 const double *arr2);
350 int wcsutil_intEq(int nelem, const int *arr1, const int *arr2);
351 int wcsutil_strEq(int nelem, char (*arr1)[72], char (*arr2)[72]);
352 void wcsutil_setAll(int nvec, int nelem, double *first);
353 void wcsutil_setAli(int nvec, int nelem, int *first);
354 void wcsutil_setBit(int nelem, const int *sel, int bits, int *array);
355 char *wcsutil_fptr2str(void (*fptr)(void), char hext[19]);
356 void wcsutil_double2str(char *buf, const char *format, double value);
357 int wcsutil_str2double(const char *buf, double *value);
358 int wcsutil_str2double2(const char *buf, double *value);
359
360 #ifdef __cplusplus
361 }
362 #endif
363
364 #endif /* WCSLIB_WCSUTIL */
wcsutil_fptr2str
char * wcsutil_fptr2str(void(*fptr)(void), char hext[19])
Translate pointer-to-function to string.
wcsutil_intEq
int wcsutil_intEq(int nelem, const int *arr1, const int *arr2)
Test for equality of two int arrays.
wcsutil_str2double2
int wcsutil_str2double2(const char *buf, double *value)
Translate string to doubles, ignoring the locale.
wcsutil_null_fill
void wcsutil_null_fill(int n, char c[])
Fill a character string with NULLs.
wcsutil_strEq
int wcsutil_strEq(int nelem, char(*arr1)[72], char(*arr2)[72])
Test for equality of two string arrays.
wcsutil_setBit
void wcsutil_setBit(int nelem, const int *sel, int bits, int *array)
Set bits in selected elements of an array.
wcsutil_allEq
int wcsutil_allEq(int nvec, int nelem, const double *first)
Test for equality of a particular vector element.
wcsutil_setAll
void wcsutil_setAll(int nvec, int nelem, double *first)
Set a particular vector element.
wcsutil_Eq
int wcsutil_Eq(int nelem, double tol, const double *arr1, const double *arr2)
Test for equality of two double arrays.
wcsutil_blank_fill
void wcsutil_blank_fill(int n, char c[])
Fill a character string with blanks.
wcsutil_double2str
void wcsutil_double2str(char *buf, const char *format, double value)
Translate double to string ignoring the locale.
wcsutil_str2double
int wcsutil_str2double(const char *buf, double *value)
Translate string to a double, ignoring the locale.
wcsutil_setAli
void wcsutil_setAli(int nvec, int nelem, int *first)
Set a particular vector element.