WCSLIB 4.23
wcsutil.h
Go to the documentation of this file.
1 /*============================================================================
2 
3  WCSLIB 4.23 - an implementation of the FITS WCS standard.
4  Copyright (C) 1995-2014, 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.23 2014/05/13 05:50:51 mcalabre Exp $
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 arrays.
113 *
114 * Given:
115 * nelem int The number of elements in each array.
116 *
117 * arr1 const double*
118 * The first array.
119 *
120 * arr2 const double*
121 * The second array
122 *
123 * Function return value:
124 * int Status return value:
125 * 0: Not equal.
126 * 1: Equal.
127 *
128 *
129 * wcsutil_intEq() - Test for equality of two int arrays
130 * -----------------------------------------------------
131 * INTERNAL USE ONLY.
132 *
133 * wcsutil_intEq() tests for equality of two int arrays.
134 *
135 * Given:
136 * nelem int The number of elements in each array.
137 *
138 * arr1 const int*
139 * The first array.
140 *
141 * arr2 const int*
142 * The second array
143 *
144 * Function return value:
145 * int Status return value:
146 * 0: Not equal.
147 * 1: Equal.
148 *
149 *
150 * wcsutil_strEq() - Test for equality of two string arrays
151 * --------------------------------------------------------
152 * INTERNAL USE ONLY.
153 *
154 * wcsutil_strEq() tests for equality of two string arrays.
155 *
156 * Given:
157 * nelem int The number of elements in each array.
158 *
159 * arr1 const char**
160 * The first array.
161 *
162 * arr2 const char**
163 * The second array
164 *
165 * Function return value:
166 * int Status return value:
167 * 0: Not equal.
168 * 1: Equal.
169 *
170 *
171 * wcsutil_setAll() - Set a particular vector element
172 * --------------------------------------------------
173 * INTERNAL USE ONLY.
174 *
175 * wcsutil_setAll() sets the value of a particular element in a set of vectors.
176 *
177 * Given:
178 * nvec int The number of vectors.
179 *
180 * nelem int The length of each vector.
181 *
182 * Given and returned:
183 * first double* Pointer to the first element in the array, the value
184 * of which is used to set the others
185 *
186 = *(first + nelem) = *first;
187 = *(first + nelem*2) = *first;
188 = :
189 = *(first + nelem*(nvec-1)) = *first;
190 *
191 * The array might be dimensioned as
192 *
193 = double v[nvec][nelem];
194 *
195 * Function return value:
196 * void
197 *
198 *
199 * wcsutil_setAli() - Set a particular vector element
200 * --------------------------------------------------
201 * INTERNAL USE ONLY.
202 *
203 * wcsutil_setAli() sets the value of a particular element in a set of vectors.
204 *
205 * Given:
206 * nvec int The number of vectors.
207 *
208 * nelem int The length of each vector.
209 *
210 * Given and returned:
211 * first int* Pointer to the first element in the array, the value
212 * of which is used to set the others
213 *
214 = *(first + nelem) = *first;
215 = *(first + nelem*2) = *first;
216 = :
217 = *(first + nelem*(nvec-1)) = *first;
218 *
219 * The array might be dimensioned as
220 *
221 = int v[nvec][nelem];
222 *
223 * Function return value:
224 * void
225 *
226 *
227 * wcsutil_setBit() - Set bits in selected elements of an array
228 * ------------------------------------------------------------
229 * INTERNAL USE ONLY.
230 *
231 * wcsutil_setBit() sets bits in selected elements of an array.
232 *
233 * Given:
234 * nelem int Number of elements in the array.
235 *
236 * sel const int*
237 * Address of a selection array of length nelem. May
238 * be specified as the null pointer in which case all
239 * elements are selected.
240 *
241 * bits int Bit mask.
242 *
243 * Given and returned:
244 * array int* Address of the array of length nelem.
245 *
246 * Function return value:
247 * void
248 *
249 *
250 * wcsutil_fptr2str() - Translate pointer-to-function to string
251 * ------------------------------------------------------------
252 * INTERNAL USE ONLY.
253 *
254 * wcsutil_fptr2str() translates a pointer-to-function to hexadecimal string
255 * representation for output. It is used by the various routines that print
256 * the contents of WCSLIB structs, noting that it is not strictly legal to
257 * type-pun a function pointer to void*. See
258 * http://stackoverflow.com/questions/2741683/how-to-format-a-function-pointer
259 *
260 * Given:
261 * fptr int(*)() Pointer to function.
262 *
263 * Returned:
264 * hext char[19] Null-terminated string. Should be at least 19 bytes
265 * in size to accomodate a 64-bit address (16 bytes in
266 * hex), plus the leading "0x" and trailing '\0'.
267 *
268 * Function return value:
269 * char * The address of hext.
270 *
271 *
272 * wcsutil_double2str() - Translate double to string ignoring the locale
273 * ---------------------------------------------------------------------
274 * INTERNAL USE ONLY.
275 *
276 * wcsutil_double2str() converts a double to a string, but unlike sprintf() it
277 * ignores the locale and always uses a '.' as the decimal separator. Also,
278 * unless it includes an exponent, the formatted value will always have a
279 * fractional part, ".0" being appended if necessary.
280 *
281 * Returned:
282 * buf char * The buffer to write the string into.
283 *
284 * Given:
285 * format char * The formatting directive, such as "%f". This
286 * may be any of the forms accepted by sprintf(), but
287 * should only include a formatting directive and
288 * nothing else. For "%g" and "%G" formats, unless it
289 * includes an exponent, the formatted value will always
290 * have a fractional part, ".0" being appended if
291 * necessary.
292 *
293 * value double The value to convert to a string.
294 *
295 *
296 * wcsutil_str2double() - Translate string to a double, ignoring the locale
297 * ------------------------------------------------------------------------
298 * INTERNAL USE ONLY.
299 *
300 * wcsutil_str2double() converts a string to a double, but unlike sscanf() it
301 * ignores the locale and always expects a '.' as the decimal separator.
302 *
303 * Given:
304 * buf char * The string containing the value
305 *
306 * format char * The formatting directive, such as "%lf". This
307 * may be any of the forms accepted by sscanf(), but
308 * should only include a single formatting directive.
309 *
310 * Returned:
311 * value double * The double value parsed from the string.
312 *
313 *===========================================================================*/
314 
315 #ifndef WCSLIB_WCSUTIL
316 #define WCSLIB_WCSUTIL
317 
318 #ifdef __cplusplus
319 extern "C" {
320 #endif
321 
322 void wcsutil_blank_fill(int n, char c[]);
323 void wcsutil_null_fill (int n, char c[]);
324 
325 int wcsutil_allEq (int nvec, int nelem, const double *first);
326 int wcsutil_Eq(int nelem, const double *arr1, const double *arr2);
327 int wcsutil_intEq(int nelem, const int *arr1, const int *arr2);
328 int wcsutil_strEq(int nelem, char (*arr1)[72], char (*arr2)[72]);
329 void wcsutil_setAll(int nvec, int nelem, double *first);
330 void wcsutil_setAli(int nvec, int nelem, int *first);
331 void wcsutil_setBit(int nelem, const int *sel, int bits, int *array);
332 char *wcsutil_fptr2str(int (*func)(void), char hext[19]);
333 int wcsutil_str2double(const char *buf, const char *format, double *value);
334 void wcsutil_double2str(char *buf, const char *format, double value);
335 
336 #ifdef __cplusplus
337 }
338 #endif
339 
340 #endif /* WCSLIB_WCSUTIL */