00001 /*============================================================================ 00002 00003 WCSLIB 4.15 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2012, 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.15 2012/09/26 14:26:05 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. Note that it is not strictly legal to 00194 * type-pun a function pointer to void*. 00195 * 00196 * See stackoverflow.com/questions/2741683/how-to-format-a-function-pointer 00197 * 00198 * Given: 00199 * fptr int (*)() Pointer to function. 00200 * 00201 * Returned: 00202 * hext char[] Null-terminated string. Should be at least 19 bytes 00203 * in size to accomodate a 64-bit address (16 bytes in 00204 * hex), plus the leading "0x" and trailing '\0'. 00205 * 00206 * Function return value: 00207 * char * The address of hext. 00208 * 00209 * 00210 * wcsutil_double2str() - Translate double to string ignoring the locale 00211 * --------------------------------------------------------------------- 00212 * INTERNAL USE ONLY. 00213 * 00214 * wcsutil_double2str() converts a double to a string, but unlike sprintf it 00215 * ignores the locale and always uses a '.' as the decimal separator. 00216 * 00217 * Returned: 00218 * buf char * The buffer to write the string into. 00219 * 00220 * Given: 00221 * format char * The formatting directive, such as "%f". This 00222 * may be any of the forms accepted by sprintf, but 00223 * should only include a formatting directive and 00224 * nothing else. 00225 * 00226 * value double The value to convert to a string. 00227 * 00228 * 00229 * wcsutil_str2double() - Translate string to a double, ignoring the locale 00230 * ------------------------------------------------------------------------ 00231 * INTERNAL USE ONLY. 00232 * 00233 * wcsutil_str2double() converts a string to a double, but unlike sscanf it 00234 * ignores the locale and always expects a '.' as the decimal separator. 00235 * 00236 * Given: 00237 * buf char * The string containing the value 00238 * 00239 * format char * The formatting directive, such as "%lf". This 00240 * may be any of the forms accepted by sscanf, but 00241 * should only include a single formatting directive. 00242 * 00243 * Returned: 00244 * value double * The double value parsed from the string. 00245 * 00246 *===========================================================================*/ 00247 00248 #ifndef WCSLIB_WCSUTIL 00249 #define WCSLIB_WCSUTIL 00250 00251 void wcsutil_blank_fill(int n, char c[]); 00252 void wcsutil_null_fill (int n, char c[]); 00253 00254 int wcsutil_allEq (int nvec, int nelem, const double *first); 00255 void wcsutil_setAll(int nvec, int nelem, double *first); 00256 void wcsutil_setAli(int nvec, int nelem, int *first); 00257 void wcsutil_setBit(int nelem, const int *sel, int bits, int *array); 00258 char *wcsutil_fptr2str(int (*func)(void), char hext[]); 00259 int wcsutil_str2double(const char *buf, const char *format, double *value); 00260 void wcsutil_double2str(char *buf, const char *format, double value); 00261 00262 #endif /* WCSLIB_WCSUTIL */