irplib_utils.h

00001 /* $Id: irplib_utils.h,v 1.52 2010/03/23 07:57:59 kmirny Exp $
00002  *
00003  * This file is part of the irplib package
00004  * Copyright (C) 2002,2003 European Southern Observatory
00005  *
00006  * This program is free software; you can redistribute it and/or modify
00007  * it under the terms of the GNU General Public License as published by
00008  * the Free Software Foundation; either version 2 of the License, or
00009  * (at your option) any later version.
00010  *
00011  * This program is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014  * GNU General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU General Public License
00017  * along with this program; if not, write to the Free Software
00018  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02111-1307  USA
00019  */
00020 
00021 /*
00022  * $Author: kmirny $
00023  * $Date: 2010/03/23 07:57:59 $
00024  * $Revision: 1.52 $
00025  * $Name: sinfo-2_2_5 $
00026  * $Log: irplib_utils.h,v $
00027  * Revision 1.52  2010/03/23 07:57:59  kmirny
00028  * DFS08552, Documentation for irplib_frameset_sort
00029  *
00030  * Revision 1.51  2009/12/16 14:59:30  cgarcia
00031  * Avoid name clash with index function
00032  *
00033  * Revision 1.50  2009/08/17 15:10:16  kmirny
00034  *
00035  * DFS07454 DFS07437
00036  *
00037  */
00038 
00039 #ifndef IRPLIB_UTILS_H
00040 #define IRPLIB_UTILS_H
00041 
00042 /*-----------------------------------------------------------------------------
00043                                    Includes
00044  -----------------------------------------------------------------------------*/
00045 
00046 #include <stdarg.h>
00047 
00048 #include <cpl.h>
00049 
00050 /*-----------------------------------------------------------------------------
00051                                    Define
00052  -----------------------------------------------------------------------------*/
00053 
00054 #define IRPLIB_XSTRINGIFY(TOSTRING) #TOSTRING
00055 #define IRPLIB_STRINGIFY(TOSTRING) IRPLIB_XSTRINGIFY(TOSTRING)
00056 
00057 /* FIXME: Remove when no longer used by any irplib-based pipelines */
00058 /* Useful for debugging */
00059 #define irplib_trace()  do if (cpl_error_get_code()) { \
00060     cpl_msg_debug(cpl_func, __FILE__ " at line %d: ERROR '%s' at %s", \
00061          __LINE__, cpl_error_get_message(), cpl_error_get_where()); \
00062   } else { \
00063     cpl_msg_debug(cpl_func, __FILE__ " at line %d: OK", __LINE__); \
00064   } while (0)
00065 
00066 #define irplib_error_recover(ESTATE, ...)                                      \
00067     do if (!cpl_errorstate_is_equal(ESTATE)) {                                 \
00068         cpl_msg_warning(cpl_func, __VA_ARGS__);                                \
00069         cpl_msg_indent_more();                                                 \
00070         cpl_errorstate_dump(ESTATE, CPL_FALSE, irplib_errorstate_warning);     \
00071         cpl_msg_indent_less();                                                 \
00072         cpl_errorstate_set(ESTATE);                                            \
00073     } while (0)
00074 
00075 
00076 
00077 /*----------------------------------------------------------------------------*/
00078 /*
00079   @brief Declare a function suitable for use with irplib_dfs_table_convert()
00080   @param  table_set_row    The name of the function to declare
00081   @see irplib_dfs_table_convert(), irplib_table_read_from_frameset()
00082 
00083 */
00084 /*----------------------------------------------------------------------------*/
00085 #define IRPLIB_UTIL_SET_ROW(table_set_row)                      \
00086     cpl_boolean table_set_row(cpl_table *,                      \
00087                               const char *,                     \
00088                               int,                              \
00089                               const cpl_frame *,                \
00090                               const cpl_parameterlist *)
00091 
00092 
00093 /*----------------------------------------------------------------------------*/
00094 /*
00095   @brief Declare a function suitable for use with irplib_dfs_table_convert()
00096   @param  table_check    The name of the function to declare
00097   @see irplib_dfs_table_convert()
00098 
00099 */
00100 /*----------------------------------------------------------------------------*/
00101 #define IRPLIB_UTIL_CHECK(table_check)                          \
00102     cpl_error_code table_check(cpl_table *,                     \
00103                                const cpl_frameset *,            \
00104                                const cpl_parameterlist *)
00105 
00106 
00107 /*----------------------------------------------------------------------------*/
00108 /*
00109   @brief   Conditional skip to the (unqiue) return point of the function
00110   @param   CONDITION    The condition to check
00111   @see cpl_error_ensure()
00112 
00113   skip_if() takes one argument, which is a logical expression.
00114   If the logical expression is false skip_if() takes no action and
00115   program execution continues.
00116   If the logical expression is true this indicates an error. In this case
00117   skip_if() will set the location of the error to the point where it
00118   was invoked in the recipe code (unless the error location is already in the
00119   recipe code). If no error code had been set, then skip_if() will set one.
00120   Finally, skip_if() causes program execution to skip to the macro 'end_skip'.
00121   The macro end_skip is located towards the end of the function, after
00122   which all resource deallocation and the function return is located.
00123 
00124   The use of skip_if() assumes the following coding practice:
00125   1) Pointers used for dynamically allocated memory that they "own" shall always
00126      point to either NULL or to allocated memory (including CPL-objects).
00127   2) Such pointers may not be reused to point to memory whose deallocation
00128      requires calls to different functions.
00129   3) Pointers of type FILE should be set NULL when not pointing to an open
00130      stream and their closing calls (fclose(), freopen(), etc.) following the
00131      'end_skip' should be guarded against such NULL pointers.
00132 
00133   Error checking with skip_if() is encouraged due to the following advantages:
00134   1) It ensures that a CPL-error code is set.
00135   2) It ensures that the location of the error in the _recipe_ code is noted.
00136   3) The error checking may be confined to a single concise line.
00137   4) It is not necessary to replicate memory deallocation for every error
00138      condition.
00139   5) If more extensive error reporting/handling is required it is not precluded
00140      by the use of skip_if().
00141   6) It allows for a single point of function return.
00142   7) It allows for optional, uniformly formatted debugging/tracing information
00143      at each macro invocation.
00144 
00145   The implementation of skip_if() uses a goto/label construction.
00146   According to Kerningham & Ritchie, The C Programming Language, 2nd edition,
00147   Section 3.8:
00148   "This organization is handy if the error-handling code is non-trivial,
00149   and if errors can occur in several places."
00150 
00151   The use of goto for any other purpose should be avoided.
00152 
00153 */
00154 /*----------------------------------------------------------------------------*/
00155 #define skip_if(CONDITION)                                                     \
00156     do {                                                                       \
00157         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00158                          goto cleanup, "Propagating a pre-existing error");    \
00159         cpl_error_ensure(!(CONDITION), cpl_error_get_code(),                   \
00160                          goto cleanup, "Propagating error");\
00161     } while (0)
00162 
00163 /*----------------------------------------------------------------------------*/
00164 /*
00165   @brief   Skip if A < B
00166   @param   A   The 1st double to compare
00167   @param   B   The 2nd double to compare
00168   @param   MSG The message to use on failure
00169   @see skip_if()
00170   @note A and B are evaluated exactly once
00171 */
00172 /*----------------------------------------------------------------------------*/
00173 #define skip_if_lt(A, B, MSG)                                                  \
00174     do {                                                                       \
00175         const double tmpa = (double)(A);                                       \
00176         const double tmpb = (double)(B);                                       \
00177                                                                                \
00178         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00179                          goto cleanup, "Propagating a pre-existing error");    \
00180         cpl_error_ensure(tmpa >= tmpb, CPL_ERROR_DATA_NOT_FOUND,               \
00181                          goto cleanup, "Need at least %g (not %g) %s",         \
00182                          tmpb, tmpa, MSG);                                     \
00183     } while (0)
00184 
00185 /*----------------------------------------------------------------------------*/
00186 /*
00187   @brief   Conditional skip on coding bug
00188   @param   CONDITION    The condition to check
00189   @see skip_if()
00190   @note unlike assert() this check cannot be disabled
00191  */
00192 /*----------------------------------------------------------------------------*/
00193 #define bug_if(CONDITION)                                                      \
00194     do {                                                                       \
00195         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00196                          goto cleanup, "Propagating an unexpected error, "     \
00197                          "please report to " PACKAGE_BUGREPORT);               \
00198         cpl_error_ensure(!(CONDITION), CPL_ERROR_UNSPECIFIED,                  \
00199                          goto cleanup, "Internal error, please report to "     \
00200                          PACKAGE_BUGREPORT);                                   \
00201     } while (0)
00202 
00203 /*----------------------------------------------------------------------------*/
00204 /*
00205   @brief   Conditional skip with error creation
00206   @param   CONDITION    The condition to check
00207   @param   ERROR        The error code to set
00208   @param   MSG          A printf-style error message. As a matter of
00209                         user-friendliness the message should mention any
00210                         value that caused the @em CONDITION to fail.
00211   @see skip_if()
00212   @note unlike assert() this check cannot be disabled
00213  */
00214 /*----------------------------------------------------------------------------*/
00215 #define error_if(CONDITION, ERROR, ...)                                 \
00216     cpl_error_ensure(cpl_error_get_code() == CPL_ERROR_NONE &&          \
00217                      !(CONDITION), ERROR, goto cleanup,  __VA_ARGS__)
00218 
00219 /*----------------------------------------------------------------------------*/
00220 /*
00221   @brief   Propagate a preexisting error, if any
00222   @param   MSG          A printf-style error message.
00223   @see skip_if()
00224  */
00225 /*----------------------------------------------------------------------------*/
00226 #define any_if(...)                                                     \
00227     cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),       \
00228                      goto cleanup,  __VA_ARGS__)
00229 
00230 /*----------------------------------------------------------------------------*/
00231 /*
00232   @brief   Define the single point of resource deallocation and return
00233   @see skip_if()
00234   @note end_skip should be used exactly once in functions that use skip_if() etc
00235 */
00236 /*----------------------------------------------------------------------------*/
00237 #define end_skip \
00238     do {                                                                     \
00239         cleanup:                                                             \
00240         if (cpl_error_get_code())                                            \
00241             cpl_msg_debug(cpl_func, "Cleanup in " __FILE__ " line %u with "  \
00242                           "error '%s' at %s", __LINE__,                      \
00243                           cpl_error_get_message(), cpl_error_get_where());   \
00244         else                                                                 \
00245             cpl_msg_debug(cpl_func, "Cleanup in " __FILE__ " line %u",       \
00246                           __LINE__);                                         \
00247     } while (0)
00248 
00249 
00250 /*----------------------------------------------------------------------------*/
00262 /*----------------------------------------------------------------------------*/
00263 #define irplib_ensure(CONDITION, ec, ...)                                      \
00264     cpl_error_ensure(CONDITION, ec, goto cleanup,  __VA_ARGS__)
00265 
00266 /*----------------------------------------------------------------------------*/
00296 /*----------------------------------------------------------------------------*/
00297 
00298 #define irplib_check(COMMAND, ...)                                             \
00299   do {                                                                         \
00300     cpl_errorstate irplib_check_prestate = cpl_errorstate_get();               \
00301     skip_if(0);                                                                \
00302     COMMAND;                                                                   \
00303         irplib_trace(); \
00304     irplib_ensure(cpl_errorstate_is_equal(irplib_check_prestate),              \
00305                   cpl_error_get_code(), __VA_ARGS__);                          \
00306         irplib_trace(); \
00307   } while (0)
00308 
00309 /*-----------------------------------------------------------------------------
00310                                    Function prototypes
00311  -----------------------------------------------------------------------------*/
00312 
00313 cpl_error_code irplib_dfs_save_image(cpl_frameset            *,
00314                                      const cpl_parameterlist *,
00315                                      const cpl_frameset      *,
00316                                      const cpl_image         *,
00317                                      cpl_type_bpp             ,
00318                                      const char              *,
00319                                      const char              *,
00320                                      const cpl_propertylist  *,
00321                                      const char              *,
00322                                      const char              *,
00323                                      const char              *);
00324 
00325 
00326 cpl_error_code irplib_dfs_save_propertylist(cpl_frameset            *,
00327                                             const cpl_parameterlist *,
00328                                             const cpl_frameset      *,
00329                                             const char              *,
00330                                             const char              *,
00331                                             const cpl_propertylist  *,
00332                                             const char              *,
00333                                             const char              *,
00334                                             const char              *);
00335 
00336 cpl_error_code irplib_dfs_save_imagelist(cpl_frameset            *,
00337                                          const cpl_parameterlist *,
00338                                          const cpl_frameset      *,
00339                                          const cpl_imagelist     *,
00340                                          cpl_type_bpp             ,
00341                                          const char              *,
00342                                          const char              *,
00343                                          const cpl_propertylist  *,
00344                                          const char              *,
00345                                          const char              *,
00346                                          const char              *);
00347 
00348 cpl_error_code irplib_dfs_save_table(cpl_frameset            *,
00349                                      const cpl_parameterlist *,
00350                                      const cpl_frameset      *,
00351                                      const cpl_table         *,
00352                                      const cpl_propertylist  *,
00353                                      const char              *,
00354                                      const char              *,
00355                                      const cpl_propertylist  *,
00356                                      const char              *,
00357                                      const char              *,
00358                                      const char              *);
00359 
00360 void irplib_reset(void);
00361 int irplib_compare_tags(cpl_frame *, cpl_frame *);
00362 const char * irplib_frameset_find_file(const cpl_frameset *, const char *);
00363 const cpl_frame * irplib_frameset_get_first_from_group(const cpl_frameset *,
00364                                                        cpl_frame_group);
00365 
00366 cpl_error_code irplib_apertures_find_max_flux(const cpl_apertures *, int *,
00367                                               int);
00368 
00369 int irplib_isinf(double value);
00370 int irplib_isnan(double value);
00371 
00372 void irplib_errorstate_warning(unsigned, unsigned, unsigned);
00373 
00374 cpl_error_code
00375 irplib_dfs_table_convert(cpl_table *, cpl_frameset *, const cpl_frameset *,
00376                          int, char, const char *, const char *,
00377                          const cpl_parameterlist *, const char *,
00378                          const cpl_propertylist *, const cpl_propertylist *,
00379                          const char *, const char *, const char *,
00380                          cpl_boolean (*)(cpl_table *, const char *, int,
00381                                             const cpl_frame *,
00382                                             const cpl_parameterlist *),
00383                          cpl_error_code (*)(cpl_table *,
00384                                             const cpl_frameset *,
00385                                             const cpl_parameterlist *));
00386 
00387 cpl_error_code irplib_table_read_from_frameset(cpl_table *,
00388                                                const cpl_frameset *,
00389                                                int,
00390                                                char,
00391                                                const cpl_parameterlist *,
00392                                                cpl_boolean (*)
00393                                                (cpl_table *, const char *,
00394                                                 int, const cpl_frame *,
00395                                                 const cpl_parameterlist *));
00396 
00397 cpl_error_code irplib_image_split(const cpl_image *,
00398                                   cpl_image *, cpl_image *, cpl_image *,
00399                                   double, cpl_boolean,
00400                                   double, cpl_boolean,
00401                                   double, double,
00402                                   cpl_boolean, cpl_boolean, cpl_boolean);
00403 
00404 void irplib_errorstate_dump_warning(unsigned, unsigned, unsigned);
00405 void irplib_errorstate_dump_info(unsigned, unsigned, unsigned);
00406 void irplib_errorstate_dump_debug(unsigned, unsigned, unsigned);
00407 /* wrapper for replace deprecated function cpl_polynomial_fit_1d_create*/
00408 cpl_polynomial * irplib_polynomial_fit_1d_create(
00409         const cpl_vector    *   x_pos,
00410         const cpl_vector    *   values,
00411         int                     degree,
00412         double              *   mse
00413         );
00414 cpl_polynomial * irplib_polynomial_fit_1d_create_chiq(
00415         const cpl_vector    *   x_pos,
00416         const cpl_vector    *   values,
00417         int                     degree,
00418         double              *   rechiq
00419         );
00420 /*----------------------------------------------------------------------------*/
00428 cpl_error_code irplib_frameset_sort(
00429         const cpl_frameset *  self,
00430         int* iindex,
00431         double* exptime);
00432 
00433 #endif

Generated on 8 Mar 2011 for SINFONI Pipeline Reference Manual by  doxygen 1.6.1