WCSLIB 4.8.2: 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.8 - an implementation of the FITS WCS standard.
    00004   Copyright (C) 1995-2011, 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   Correspondence concerning WCSLIB may be directed to:
    00022     Internet email: mcalabre@atnf.csiro.au
    00023     Postal address: Dr. Mark Calabretta
    00024                     Australia Telescope National Facility, CSIRO
    00025                     PO Box 76
    00026                     Epping NSW 1710
    00027                     AUSTRALIA
    00028
    00029   Author: Mark Calabretta, Australia Telescope National Facility
    00030   http://www.atnf.csiro.au/~mcalabre/index.html
    00031   $Id: wcsutil.h,v 4.8.1.1 2011/08/15 08:07:06 cal103 Exp cal103 $
    00032 *=============================================================================
    00033 *
    00034 * Summary of the wcsutil routines
    00035 * -------------------------------
    00036 * Simple utility functions for internal use only by WCSLIB.  They are
    00037 * documented here solely as an aid to understanding the code.  They are not
    00038 * intended for external use - the API may change without notice!
    00039 *
    00040 *
    00041 * wcsutil_blank_fill() - Fill a character string with blanks
    00042 * ----------------------------------------------------------
    00043 * INTERNAL USE ONLY.
    00044 *
    00045 * wcsutil_blank_fill() pads a character string with blanks starting with the
    00046 * terminating NULL character.
    00047 *
    00048 * Used by the Fortran wrapper functions in translating C character strings
    00049 * into Fortran CHARACTER variables.
    00050 *
    00051 * Given:
    00052 *   n         int       Length of the character array, c[].
    00053 *
    00054 * Given and returned:
    00055 *   c         char[]    The character string.  It will not be null-terminated
    00056 *                       on return.
    00057 *
    00058 * Function return value:
    00059 *             void
    00060 *
    00061 *
    00062 * wcsutil_null_fill() - Fill a character string with NULLs
    00063 * --------------------------------------------------------
    00064 * INTERNAL USE ONLY.
    00065 *
    00066 * wcsutil_null_fill() strips off trailing blanks and pads the character array
    00067 * holding the string with NULL characters.
    00068 *
    00069 * Used mainly to make character strings intelligible in the GNU debugger which
    00070 * prints the rubbish following the terminating NULL, obscuring the valid part
    00071 * of the string.
    00072 *
    00073 * Given:
    00074 *   n         int       Number of characters.
    00075 *
    00076 * Given and returned:
    00077 *   c         char[]    The character string.
    00078 *
    00079 * Function return value:
    00080 *             void
    00081 *
    00082 *
    00083 * wcsutil_allEq() - Test for equality of a particular vector element
    00084 * ------------------------------------------------------------------
    00085 * INTERNAL USE ONLY.
    00086 *
    00087 * wcsutil_allEq() tests for equality of a particular element in a set of
    00088 * vectors.
    00089 *
    00090 * Given:
    00091 *   nvec      int       The number of vectors.
    00092 *
    00093 *   nelem     int       The length of each vector.
    00094 *
    00095 *   first     const double*
    00096 *                       Pointer to the first element to test in the array.
    00097 *                       The elements tested for equality are
    00098 *
    00099 =                         *first == *(first + nelem)
    00100 =                                == *(first + nelem*2)
    00101 =                                           :
    00102 =                                == *(first + nelem*(nvec-1));
    00103 *
    00104 *                       The array might be dimensioned as
    00105 *
    00106 =                         double v[nvec][nelem];
    00107 *
    00108 * Function return value:
    00109 *             int       Status return value:
    00110 *                         0: Not all equal.
    00111 *                         1: All equal.
    00112 *
    00113 *
    00114 * wcsutil_setAll() - Set a particular vector element
    00115 * --------------------------------------------------
    00116 * INTERNAL USE ONLY.
    00117 *
    00118 * wcsutil_setAll() sets the value of a particular element in a set of vectors.
    00119 *
    00120 * Given:
    00121 *   nvec      int       The number of vectors.
    00122 *
    00123 *   nelem     int       The length of each vector.
    00124 *
    00125 * Given and returned:
    00126 *   first     double*   Pointer to the first element in the array, the value
    00127 *                       of which is used to set the others
    00128 *
    00129 =                         *(first + nelem) = *first;
    00130 =                         *(first + nelem*2) = *first;
    00131 =                                 :
    00132 =                         *(first + nelem*(nvec-1)) = *first;
    00133 *
    00134 *                       The array might be dimensioned as
    00135 *
    00136 =                         double v[nvec][nelem];
    00137 *
    00138 * Function return value:
    00139 *             void
    00140 *
    00141 *
    00142 * wcsutil_setAli() - Set a particular vector element
    00143 * --------------------------------------------------
    00144 * INTERNAL USE ONLY.
    00145 *
    00146 * wcsutil_setAli() sets the value of a particular element in a set of vectors.
    00147 *
    00148 * Given:
    00149 *   nvec      int       The number of vectors.
    00150 *
    00151 *   nelem     int       The length of each vector.
    00152 *
    00153 * Given and returned:
    00154 *   first     int*      Pointer to the first element in the array, the value
    00155 *                       of which is used to set the others
    00156 *
    00157 =                         *(first + nelem) = *first;
    00158 =                         *(first + nelem*2) = *first;
    00159 =                                 :
    00160 =                         *(first + nelem*(nvec-1)) = *first;
    00161 *
    00162 *                       The array might be dimensioned as
    00163 *
    00164 =                         int v[nvec][nelem];
    00165 *
    00166 * Function return value:
    00167 *             void
    00168 *
    00169 *
    00170 * wcsutil_setBit() - Set bits in selected elements of an array
    00171 * ------------------------------------------------------------
    00172 * INTERNAL USE ONLY.
    00173 *
    00174 * wcsutil_setBit() sets bits in selected elements of an array.
    00175 *
    00176 * Given:
    00177 *   nelem     int       Number of elements in the array.
    00178 *
    00179 *   sel       const int*
    00180 *                       Address of a selection array of length nelem.  May
    00181 *                       be specified as the null pointer in which case all
    00182 *                       elements are selected.
    00183 *
    00184 *   bits      int       Bit mask.
    00185 *
    00186 * Given and returned:
    00187 *   array     int*      Address of the array of length nelem.
    00188 *
    00189 * Function return value:
    00190 *             void
    00191 *
    00192 *
    00193 * wcsutil_fptr2str() - Translate pointer-to-function to string
    00194 * ------------------------------------------------------------
    00195 * INTERNAL USE ONLY.
    00196 *
    00197 * wcsutil_fptr2str() translates a pointer-to-function to hexadecimal string
    00198 * representation for output.  It is used by the various routines that print
    00199 * the contents of WCSLIB structs.  Note that it is not strictly legal to
    00200 * type-pun a function pointer to void*.
    00201 *
    00202 * See stackoverflow.com/questions/2741683/how-to-format-a-function-pointer
    00203 *
    00204 * Given:
    00205 *   fptr      int (*)() Pointer to function.
    00206 *
    00207 * Returned:
    00208 *   hext      char[]    Null-terminated string.  Should be at least 19 bytes
    00209 *                       in size to accomodate a 64-bit address (16 bytes in
    00210 *                       hex), plus the leading "0x" and trailing '\0'.
    00211 *
    00212 * Function return value:
    00213 *             char *    The address of hext.
    00214 *
    00215 *===========================================================================*/
    00216
    00217 #ifndef WCSLIB_WCSUTIL
    00218 #define WCSLIB_WCSUTIL
    00219
    00220 void wcsutil_blank_fill(int n, char c[]);
    00221 void wcsutil_null_fill (int n, char c[]);
    00222
    00223 int  wcsutil_allEq (int nvec, int nelem, const double *first);
    00224 void wcsutil_setAll(int nvec, int nelem, double *first);
    00225 void wcsutil_setAli(int nvec, int nelem, int *first);
    00226 void wcsutil_setBit(int nelem, const int *sel, int bits, int *array);
    00227 char *wcsutil_fptr2str(int (*func)(), char hext[]);
    00228
    00229 #endif /* WCSLIB_WCSUTIL */