00001 /*============================================================================ 00002 00003 WCSLIB 4.17 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2013, Mark Calabretta 00005 00006 This file is part of WCSLIB. 00007 00008 WCSLIB is free software: you can redistribute it and/or modify it under the 00009 terms of the GNU Lesser General Public License as published by the Free 00010 Software Foundation, either version 3 of the License, or (at your option) 00011 any later version. 00012 00013 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY 00014 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 00016 more details. 00017 00018 You should have received a copy of the GNU Lesser General Public License 00019 along with WCSLIB. If not, see http://www.gnu.org/licenses. 00020 00021 Direct correspondence concerning WCSLIB to mark@calabretta.id.au 00022 00023 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO. 00024 http://www.atnf.csiro.au/people/Mark.Calabretta 00025 $Id: wcsutil.h,v 4.17 2013/01/29 05:29:20 cal103 Exp $ 00026 *============================================================================= 00027 * 00028 * Summary of the wcsutil routines 00029 * ------------------------------- 00030 * Simple utility functions for internal use only by WCSLIB. They are 00031 * documented here solely as an aid to understanding the code. They are not 00032 * intended for external use - the API may change without notice! 00033 * 00034 * 00035 * wcsutil_blank_fill() - Fill a character string with blanks 00036 * ---------------------------------------------------------- 00037 * INTERNAL USE ONLY. 00038 * 00039 * wcsutil_blank_fill() pads a character string with blanks starting with the 00040 * terminating NULL character. 00041 * 00042 * Used by the Fortran wrapper functions in translating C character strings 00043 * into Fortran CHARACTER variables. 00044 * 00045 * Given: 00046 * n int Length of the character array, c[]. 00047 * 00048 * Given and returned: 00049 * c char[] The character string. It will not be null-terminated 00050 * on return. 00051 * 00052 * Function return value: 00053 * void 00054 * 00055 * 00056 * wcsutil_null_fill() - Fill a character string with NULLs 00057 * -------------------------------------------------------- 00058 * INTERNAL USE ONLY. 00059 * 00060 * wcsutil_null_fill() strips off trailing blanks and pads the character array 00061 * holding the string with NULL characters. 00062 * 00063 * Used mainly to make character strings intelligible in the GNU debugger which 00064 * prints the rubbish following the terminating NULL, obscuring the valid part 00065 * of the string. 00066 * 00067 * Given: 00068 * n int Number of characters. 00069 * 00070 * Given and returned: 00071 * c char[] The character string. 00072 * 00073 * Function return value: 00074 * void 00075 * 00076 * 00077 * wcsutil_allEq() - Test for equality of a particular vector element 00078 * ------------------------------------------------------------------ 00079 * INTERNAL USE ONLY. 00080 * 00081 * wcsutil_allEq() tests for equality of a particular element in a set of 00082 * vectors. 00083 * 00084 * Given: 00085 * nvec int The number of vectors. 00086 * 00087 * nelem int The length of each vector. 00088 * 00089 * first const double* 00090 * Pointer to the first element to test in the array. 00091 * The elements tested for equality are 00092 * 00093 = *first == *(first + nelem) 00094 = == *(first + nelem*2) 00095 = : 00096 = == *(first + nelem*(nvec-1)); 00097 * 00098 * The array might be dimensioned as 00099 * 00100 = double v[nvec][nelem]; 00101 * 00102 * Function return value: 00103 * int Status return value: 00104 * 0: Not all equal. 00105 * 1: All equal. 00106 * 00107 * 00108 * wcsutil_setAll() - Set a particular vector element 00109 * -------------------------------------------------- 00110 * INTERNAL USE ONLY. 00111 * 00112 * wcsutil_setAll() sets the value of a particular element in a set of vectors. 00113 * 00114 * Given: 00115 * nvec int The number of vectors. 00116 * 00117 * nelem int The length of each vector. 00118 * 00119 * Given and returned: 00120 * first double* Pointer to the first element in the array, the value 00121 * of which is used to set the others 00122 * 00123 = *(first + nelem) = *first; 00124 = *(first + nelem*2) = *first; 00125 = : 00126 = *(first + nelem*(nvec-1)) = *first; 00127 * 00128 * The array might be dimensioned as 00129 * 00130 = double v[nvec][nelem]; 00131 * 00132 * Function return value: 00133 * void 00134 * 00135 * 00136 * wcsutil_setAli() - Set a particular vector element 00137 * -------------------------------------------------- 00138 * INTERNAL USE ONLY. 00139 * 00140 * wcsutil_setAli() sets the value of a particular element in a set of vectors. 00141 * 00142 * Given: 00143 * nvec int The number of vectors. 00144 * 00145 * nelem int The length of each vector. 00146 * 00147 * Given and returned: 00148 * first int* Pointer to the first element in the array, the value 00149 * of which is used to set the others 00150 * 00151 = *(first + nelem) = *first; 00152 = *(first + nelem*2) = *first; 00153 = : 00154 = *(first + nelem*(nvec-1)) = *first; 00155 * 00156 * The array might be dimensioned as 00157 * 00158 = int v[nvec][nelem]; 00159 * 00160 * Function return value: 00161 * void 00162 * 00163 * 00164 * wcsutil_setBit() - Set bits in selected elements of an array 00165 * ------------------------------------------------------------ 00166 * INTERNAL USE ONLY. 00167 * 00168 * wcsutil_setBit() sets bits in selected elements of an array. 00169 * 00170 * Given: 00171 * nelem int Number of elements in the array. 00172 * 00173 * sel const int* 00174 * Address of a selection array of length nelem. May 00175 * be specified as the null pointer in which case all 00176 * elements are selected. 00177 * 00178 * bits int Bit mask. 00179 * 00180 * Given and returned: 00181 * array int* Address of the array of length nelem. 00182 * 00183 * Function return value: 00184 * void 00185 * 00186 * 00187 * wcsutil_fptr2str() - Translate pointer-to-function to string 00188 * ------------------------------------------------------------ 00189 * INTERNAL USE ONLY. 00190 * 00191 * wcsutil_fptr2str() translates a pointer-to-function to hexadecimal string 00192 * representation for output. It is used by the various routines that print 00193 * the contents of WCSLIB structs, noting that it is not strictly legal to 00194 * type-pun a function pointer to void*. See 00195 * http://stackoverflow.com/questions/2741683/how-to-format-a-function-pointer 00196 * 00197 * Given: 00198 * fptr int(*)() Pointer to function. 00199 * 00200 * Returned: 00201 * hext char[19] Null-terminated string. Should be at least 19 bytes 00202 * in size to accomodate a 64-bit address (16 bytes in 00203 * hex), plus the leading "0x" and trailing '\0'. 00204 * 00205 * Function return value: 00206 * char * The address of hext. 00207 * 00208 * 00209 * wcsutil_double2str() - Translate double to string ignoring the locale 00210 * --------------------------------------------------------------------- 00211 * INTERNAL USE ONLY. 00212 * 00213 * wcsutil_double2str() converts a double to a string, but unlike sprintf() it 00214 * ignores the locale and always uses a '.' as the decimal separator. 00215 * 00216 * Returned: 00217 * buf char * The buffer to write the string into. 00218 * 00219 * Given: 00220 * format char * The formatting directive, such as "%f". This 00221 * may be any of the forms accepted by sprintf(), but 00222 * should only include a formatting directive and 00223 * nothing else. 00224 * 00225 * value double The value to convert to a string. 00226 * 00227 * 00228 * wcsutil_str2double() - Translate string to a double, ignoring the locale 00229 * ------------------------------------------------------------------------ 00230 * INTERNAL USE ONLY. 00231 * 00232 * wcsutil_str2double() converts a string to a double, but unlike sscanf() it 00233 * ignores the locale and always expects a '.' as the decimal separator. 00234 * 00235 * Given: 00236 * buf char * The string containing the value 00237 * 00238 * format char * The formatting directive, such as "%lf". This 00239 * may be any of the forms accepted by sscanf(), but 00240 * should only include a single formatting directive. 00241 * 00242 * Returned: 00243 * value double * The double value parsed from the string. 00244 * 00245 *===========================================================================*/ 00246 00247 #ifndef WCSLIB_WCSUTIL 00248 #define WCSLIB_WCSUTIL 00249 00250 #ifdef __cplusplus 00251 extern "C" { 00252 #endif 00253 00254 void wcsutil_blank_fill(int n, char c[]); 00255 void wcsutil_null_fill (int n, char c[]); 00256 00257 int wcsutil_allEq (int nvec, int nelem, const double *first); 00258 void wcsutil_setAll(int nvec, int nelem, double *first); 00259 void wcsutil_setAli(int nvec, int nelem, int *first); 00260 void wcsutil_setBit(int nelem, const int *sel, int bits, int *array); 00261 char *wcsutil_fptr2str(int (*func)(void), char hext[19]); 00262 int wcsutil_str2double(const char *buf, const char *format, double *value); 00263 void wcsutil_double2str(char *buf, const char *format, double value); 00264 00265 #ifdef __cplusplus 00266 } 00267 #endif 00268 00269 #endif /* WCSLIB_WCSUTIL */