WCSLIB 4.17: wcsutil.h Source File

- Main Page
- Related Pages
- Data Structures
- Files

# wcsutil.h

Go to the documentation of this file.

    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 */