irplib_utils.h

00001 /* $Id: irplib_utils.h,v 1.57 2013/02/27 16:02:02 jtaylor 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: jtaylor $
00023  * $Date: 2013/02/27 16:02:02 $
00024  * $Revision: 1.57 $
00025  * $Name: HEAD $
00026  * $Log: irplib_utils.h,v $
00027  * Revision 1.57  2013/02/27 16:02:02  jtaylor
00028  * add diagnostic pragma macros
00029  *
00030  * Revision 1.56  2012/08/06 06:14:18  llundin
00031  * irplib_errorstate_warning(): Replaced by cpl_errorstate_dump_one_warning() from CPL 6.X
00032  *
00033  * Revision 1.55  2011/06/01 06:47:56  llundin
00034  * skip_if_lt(): Fix previous edits switch of A and B in error message
00035  *
00036  * Revision 1.54  2011/05/26 08:08:56  llundin
00037  * skip_if_lt(): Support printf-style error message, name-space protect temporary variables
00038  *
00039  * Revision 1.53  2011/05/09 07:51:18  llundin
00040  * irplib_dfs_save_image_(): Modified from cpl_dfs_save_image(). irplib_dfs_save_image(): Use irplib_dfs_save_image_()
00041  *
00042  * Revision 1.52  2010/03/23 07:57:59  kmirny
00043  * DFS08552, Documentation for irplib_frameset_sort
00044  *
00045  * Revision 1.51  2009/12/16 14:59:30  cgarcia
00046  * Avoid name clash with index function
00047  *
00048  * Revision 1.50  2009/08/17 15:10:16  kmirny
00049  *
00050  * DFS07454 DFS07437
00051  *
00052  */
00053 
00054 #ifndef IRPLIB_UTILS_H
00055 #define IRPLIB_UTILS_H
00056 
00057 /*-----------------------------------------------------------------------------
00058                                    Includes
00059  -----------------------------------------------------------------------------*/
00060 
00061 #include <cpl.h>
00062 
00063 #include <stdarg.h>
00064 
00065 /*-----------------------------------------------------------------------------
00066                                    Define
00067  -----------------------------------------------------------------------------*/
00068 
00069 #define IRPLIB_XSTRINGIFY(TOSTRING) #TOSTRING
00070 #define IRPLIB_STRINGIFY(TOSTRING) IRPLIB_XSTRINGIFY(TOSTRING)
00071 
00072 
00073 #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)
00074 #define IRPLIB_DIAG_PRAGMA_PUSH_IGN(x)        \
00075     _Pragma("GCC diagnostic push") \
00076     _Pragma(IRPLIB_STRINGIFY(GCC diagnostic ignored #x))
00077 #define IRPLIB_DIAG_PRAGMA_PUSH_ERR(x)        \
00078     _Pragma("GCC diagnostic push") \
00079     _Pragma(IRPLIB_STRINGIFY(GCC diagnostic error #x))
00080 #define IRPLIB_DIAG_PRAGMA_POP \
00081     _Pragma("GCC diagnostic pop")
00082 #else
00083 #define IRPLIB_DIAG_PRAGMA_PUSH_IGN(x)
00084 #define IRPLIB_DIAG_PRAGMA_PUSH_ERR(x)
00085 #define IRPLIB_DIAG_PRAGMA_POP
00086 #endif
00087 
00088 
00089 /* FIXME: Remove when no longer used by any irplib-based pipelines */
00090 /* Useful for debugging */
00091 #define irplib_trace()  do if (cpl_error_get_code()) { \
00092     cpl_msg_debug(cpl_func, __FILE__ " at line %d: ERROR '%s' at %s", \
00093          __LINE__, cpl_error_get_message(), cpl_error_get_where()); \
00094   } else { \
00095     cpl_msg_debug(cpl_func, __FILE__ " at line %d: OK", __LINE__); \
00096   } while (0)
00097 
00098 #define irplib_error_recover(ESTATE, ...)                       \
00099     do if (!cpl_errorstate_is_equal(ESTATE)) {                  \
00100         cpl_msg_warning(cpl_func, __VA_ARGS__);                 \
00101         cpl_msg_indent_more();                                  \
00102         cpl_errorstate_dump(ESTATE, CPL_FALSE,                  \
00103                             cpl_errorstate_dump_one_warning);   \
00104         cpl_msg_indent_less();                                  \
00105         cpl_errorstate_set(ESTATE);                             \
00106     } while (0)
00107 
00108 
00109 
00110 /*----------------------------------------------------------------------------*/
00111 /*
00112   @brief Declare a function suitable for use with irplib_dfs_table_convert()
00113   @param  table_set_row    The name of the function to declare
00114   @see irplib_dfs_table_convert(), irplib_table_read_from_frameset()
00115 
00116 */
00117 /*----------------------------------------------------------------------------*/
00118 #define IRPLIB_UTIL_SET_ROW(table_set_row)                      \
00119     cpl_boolean table_set_row(cpl_table *,                      \
00120                               const char *,                     \
00121                               int,                              \
00122                               const cpl_frame *,                \
00123                               const cpl_parameterlist *)
00124 
00125 
00126 /*----------------------------------------------------------------------------*/
00127 /*
00128   @brief Declare a function suitable for use with irplib_dfs_table_convert()
00129   @param  table_check    The name of the function to declare
00130   @see irplib_dfs_table_convert()
00131 
00132 */
00133 /*----------------------------------------------------------------------------*/
00134 #define IRPLIB_UTIL_CHECK(table_check)                          \
00135     cpl_error_code table_check(cpl_table *,                     \
00136                                const cpl_frameset *,            \
00137                                const cpl_parameterlist *)
00138 
00139 
00140 /*----------------------------------------------------------------------------*/
00141 /*
00142   @brief   Conditional skip to the (unqiue) return point of the function
00143   @param   CONDITION    The condition to check
00144   @see cpl_error_ensure()
00145 
00146   skip_if() takes one argument, which is a logical expression.
00147   If the logical expression is false skip_if() takes no action and
00148   program execution continues.
00149   If the logical expression is true this indicates an error. In this case
00150   skip_if() will set the location of the error to the point where it
00151   was invoked in the recipe code (unless the error location is already in the
00152   recipe code). If no error code had been set, then skip_if() will set one.
00153   Finally, skip_if() causes program execution to skip to the macro 'end_skip'.
00154   The macro end_skip is located towards the end of the function, after
00155   which all resource deallocation and the function return is located.
00156 
00157   The use of skip_if() assumes the following coding practice:
00158   1) Pointers used for dynamically allocated memory that they "own" shall always
00159      point to either NULL or to allocated memory (including CPL-objects).
00160   2) Such pointers may not be reused to point to memory whose deallocation
00161      requires calls to different functions.
00162   3) Pointers of type FILE should be set NULL when not pointing to an open
00163      stream and their closing calls (fclose(), freopen(), etc.) following the
00164      'end_skip' should be guarded against such NULL pointers.
00165 
00166   Error checking with skip_if() is encouraged due to the following advantages:
00167   1) It ensures that a CPL-error code is set.
00168   2) It ensures that the location of the error in the _recipe_ code is noted.
00169   3) The error checking may be confined to a single concise line.
00170   4) It is not necessary to replicate memory deallocation for every error
00171      condition.
00172   5) If more extensive error reporting/handling is required it is not precluded
00173      by the use of skip_if().
00174   6) It allows for a single point of function return.
00175   7) It allows for optional, uniformly formatted debugging/tracing information
00176      at each macro invocation.
00177 
00178   The implementation of skip_if() uses a goto/label construction.
00179   According to Kerningham & Ritchie, The C Programming Language, 2nd edition,
00180   Section 3.8:
00181   "This organization is handy if the error-handling code is non-trivial,
00182   and if errors can occur in several places."
00183 
00184   The use of goto for any other purpose should be avoided.
00185 
00186 */
00187 /*----------------------------------------------------------------------------*/
00188 #define skip_if(CONDITION)                                                     \
00189     do {                                                                       \
00190         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00191                          goto cleanup, "Propagating a pre-existing error");    \
00192         cpl_error_ensure(!(CONDITION), cpl_error_get_code(),                   \
00193                          goto cleanup, "Propagating error");\
00194     } while (0)
00195 
00196 /*----------------------------------------------------------------------------*/
00197 /*
00198   @brief   Skip if A < B
00199   @param   A   The 1st double to compare
00200   @param   B   The 2nd double to compare
00201   @param   MSG A printf-style error message, 1st arg should be a string literal
00202   @see skip_if()
00203   @note A and B are evaluated exactly once
00204 
00205   If no CPL error is set, sets CPL_ERROR_DATA_NOT_FOUND on failure
00206 */
00207 /*----------------------------------------------------------------------------*/
00208 #define skip_if_lt(A, B, ...)                                                  \
00209     do {                                                                       \
00210         /* Name-space protected one-time only evaluation */                    \
00211         const double irplib_utils_a = (double)(A);                             \
00212         const double irplib_utils_b = (double)(B);                             \
00213                                                                                \
00214         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00215                          goto cleanup, "Propagating a pre-existing error");    \
00216         if (irplib_utils_a < irplib_utils_b) {                                 \
00217             char * irplib_utils_msg = cpl_sprintf(__VA_ARGS__);                \
00218             (void)cpl_error_set_message(cpl_func, CPL_ERROR_DATA_NOT_FOUND,    \
00219                                         "Need at least %g (not %g) %s",        \
00220                                         irplib_utils_b, irplib_utils_a,        \
00221                                         irplib_utils_msg);                     \
00222             cpl_free(irplib_utils_msg);                                        \
00223             goto cleanup;                                                      \
00224         }                                                                      \
00225     } while (0)
00226 
00227 /*----------------------------------------------------------------------------*/
00228 /*
00229   @brief   Conditional skip on coding bug
00230   @param   CONDITION    The condition to check
00231   @see skip_if()
00232   @note unlike assert() this check cannot be disabled
00233  */
00234 /*----------------------------------------------------------------------------*/
00235 #define bug_if(CONDITION)                                                      \
00236     do {                                                                       \
00237         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00238                          goto cleanup, "Propagating an unexpected error, "     \
00239                          "please report to " PACKAGE_BUGREPORT);               \
00240         cpl_error_ensure(!(CONDITION), CPL_ERROR_UNSPECIFIED,                  \
00241                          goto cleanup, "Internal error, please report to "     \
00242                          PACKAGE_BUGREPORT);                                   \
00243     } while (0)
00244 
00245 /*----------------------------------------------------------------------------*/
00246 /*
00247   @brief   Conditional skip with error creation
00248   @param   CONDITION    The condition to check
00249   @param   ERROR        The error code to set
00250   @param   MSG          A printf-style error message. As a matter of
00251                         user-friendliness the message should mention any
00252                         value that caused the @em CONDITION to fail.
00253   @see skip_if()
00254   @note unlike assert() this check cannot be disabled
00255  */
00256 /*----------------------------------------------------------------------------*/
00257 #define error_if(CONDITION, ERROR, ...)                                 \
00258     cpl_error_ensure(cpl_error_get_code() == CPL_ERROR_NONE &&          \
00259                      !(CONDITION), ERROR, goto cleanup,  __VA_ARGS__)
00260 
00261 /*----------------------------------------------------------------------------*/
00262 /*
00263   @brief   Propagate a preexisting error, if any
00264   @param   MSG          A printf-style error message.
00265   @see skip_if()
00266  */
00267 /*----------------------------------------------------------------------------*/
00268 #define any_if(...)                                                     \
00269     cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),       \
00270                      goto cleanup,  __VA_ARGS__)
00271 
00272 /*----------------------------------------------------------------------------*/
00273 /*
00274   @brief   Define the single point of resource deallocation and return
00275   @see skip_if()
00276   @note end_skip should be used exactly once in functions that use skip_if() etc
00277 */
00278 /*----------------------------------------------------------------------------*/
00279 #define end_skip \
00280     do {                                                                     \
00281         cleanup:                                                             \
00282         if (cpl_error_get_code())                                            \
00283             cpl_msg_debug(cpl_func, "Cleanup in " __FILE__ " line %u with "  \
00284                           "error '%s' at %s", __LINE__,                      \
00285                           cpl_error_get_message(), cpl_error_get_where());   \
00286         else                                                                 \
00287             cpl_msg_debug(cpl_func, "Cleanup in " __FILE__ " line %u",       \
00288                           __LINE__);                                         \
00289     } while (0)
00290 
00291 
00292 /*----------------------------------------------------------------------------*/
00304 /*----------------------------------------------------------------------------*/
00305 #define irplib_ensure(CONDITION, ec, ...)                                      \
00306     cpl_error_ensure(CONDITION, ec, goto cleanup,  __VA_ARGS__)
00307 
00308 /*----------------------------------------------------------------------------*/
00338 /*----------------------------------------------------------------------------*/
00339 
00340 #define irplib_check(COMMAND, ...)                                             \
00341   do {                                                                         \
00342     cpl_errorstate irplib_check_prestate = cpl_errorstate_get();               \
00343     skip_if(0);                                                                \
00344     COMMAND;                                                                   \
00345         irplib_trace(); \
00346     irplib_ensure(cpl_errorstate_is_equal(irplib_check_prestate),              \
00347                   cpl_error_get_code(), __VA_ARGS__);                          \
00348         irplib_trace(); \
00349   } while (0)
00350 
00351 /*-----------------------------------------------------------------------------
00352                                    Function prototypes
00353  -----------------------------------------------------------------------------*/
00354 
00355 cpl_error_code irplib_dfs_save_image(cpl_frameset            *,
00356                                      const cpl_parameterlist *,
00357                                      const cpl_frameset      *,
00358                                      const cpl_image         *,
00359                                      cpl_type_bpp             ,
00360                                      const char              *,
00361                                      const char              *,
00362                                      const cpl_propertylist  *,
00363                                      const char              *,
00364                                      const char              *,
00365                                      const char              *);
00366 
00367 
00368 cpl_error_code irplib_dfs_save_propertylist(cpl_frameset            *,
00369                                             const cpl_parameterlist *,
00370                                             const cpl_frameset      *,
00371                                             const char              *,
00372                                             const char              *,
00373                                             const cpl_propertylist  *,
00374                                             const char              *,
00375                                             const char              *,
00376                                             const char              *);
00377 
00378 cpl_error_code irplib_dfs_save_imagelist(cpl_frameset            *,
00379                                          const cpl_parameterlist *,
00380                                          const cpl_frameset      *,
00381                                          const cpl_imagelist     *,
00382                                          cpl_type_bpp             ,
00383                                          const char              *,
00384                                          const char              *,
00385                                          const cpl_propertylist  *,
00386                                          const char              *,
00387                                          const char              *,
00388                                          const char              *);
00389 
00390 cpl_error_code irplib_dfs_save_table(cpl_frameset            *,
00391                                      const cpl_parameterlist *,
00392                                      const cpl_frameset      *,
00393                                      const cpl_table         *,
00394                                      const cpl_propertylist  *,
00395                                      const char              *,
00396                                      const char              *,
00397                                      const cpl_propertylist  *,
00398                                      const char              *,
00399                                      const char              *,
00400                                      const char              *);
00401 
00402 cpl_error_code irplib_dfs_save_image_(cpl_frameset            *,
00403                                       cpl_propertylist        *,
00404                                       const cpl_parameterlist *,
00405                                       const cpl_frameset      *,
00406                                       const cpl_frame         *,
00407                                       const cpl_image         *,
00408                                       cpl_type                 ,
00409                                       const char              *,
00410                                       const cpl_propertylist  *,
00411                                       const char              *,
00412                                       const char              *,
00413                                       const char              *);
00414 
00415 void irplib_reset(void);
00416 int irplib_compare_tags(cpl_frame *, cpl_frame *);
00417 const char * irplib_frameset_find_file(const cpl_frameset *, const char *);
00418 const cpl_frame * irplib_frameset_get_first_from_group(const cpl_frameset *,
00419                                                        cpl_frame_group);
00420 
00421 cpl_error_code irplib_apertures_find_max_flux(const cpl_apertures *, int *,
00422                                               int);
00423 
00424 int irplib_isinf(double value);
00425 int irplib_isnan(double value);
00426 
00427 cpl_error_code
00428 irplib_dfs_table_convert(cpl_table *, cpl_frameset *, const cpl_frameset *,
00429                          int, char, const char *, const char *,
00430                          const cpl_parameterlist *, const char *,
00431                          const cpl_propertylist *, const cpl_propertylist *,
00432                          const char *, const char *, const char *,
00433                          cpl_boolean (*)(cpl_table *, const char *, int,
00434                                             const cpl_frame *,
00435                                             const cpl_parameterlist *),
00436                          cpl_error_code (*)(cpl_table *,
00437                                             const cpl_frameset *,
00438                                             const cpl_parameterlist *));
00439 
00440 cpl_error_code irplib_table_read_from_frameset(cpl_table *,
00441                                                const cpl_frameset *,
00442                                                int,
00443                                                char,
00444                                                const cpl_parameterlist *,
00445                                                cpl_boolean (*)
00446                                                (cpl_table *, const char *,
00447                                                 int, const cpl_frame *,
00448                                                 const cpl_parameterlist *));
00449 
00450 cpl_error_code irplib_image_split(const cpl_image *,
00451                                   cpl_image *, cpl_image *, cpl_image *,
00452                                   double, cpl_boolean,
00453                                   double, cpl_boolean,
00454                                   double, double,
00455                                   cpl_boolean, cpl_boolean, cpl_boolean);
00456 
00457 void irplib_errorstate_dump_warning(unsigned, unsigned, unsigned);
00458 void irplib_errorstate_dump_info(unsigned, unsigned, unsigned);
00459 void irplib_errorstate_dump_debug(unsigned, unsigned, unsigned);
00460 /* wrapper for replace deprecated function cpl_polynomial_fit_1d_create*/
00461 cpl_polynomial * irplib_polynomial_fit_1d_create(
00462         const cpl_vector    *   x_pos,
00463         const cpl_vector    *   values,
00464         int                     degree,
00465         double              *   mse
00466         );
00467 cpl_polynomial * irplib_polynomial_fit_1d_create_chiq(
00468         const cpl_vector    *   x_pos,
00469         const cpl_vector    *   values,
00470         int                     degree,
00471         double              *   rechiq
00472         );
00473 /*----------------------------------------------------------------------------*/
00481 cpl_error_code irplib_frameset_sort(
00482         const cpl_frameset *  self,
00483         int* iindex,
00484         double* exptime);
00485 
00486 #endif

Generated on 3 Mar 2013 for SINFONI Pipeline Reference Manual by  doxygen 1.6.1