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