libdatrwxx [MERGE] provide recent changes on master to branch

Merge branch 'master' into 24-libdatrwxx-miniseed-format-specification

CHANGELOG

@@ -3,6 +3,12 @@ this is <CHANGELOG>
 Recent development in Seitosh (bug fixes, new features, etc)
 ------------------------------------------------------------
 
+12.07.2016 (fcc2520e9): libdatrwxx: new error message format
+
+   Let libdatrwxx output more user-friendly error messages. These messages can
+   contain more detailed and comprehensive information regarding the cause of
+   the error message and can provide hints how to handle the situation.
+
 06.07.2016 (4342d3a79): libdatrwxx provides new format modifiers
 
   Format modifiers skipcheck and nonfatal which can be applied to the mseed

Makefile

@@ -16,8 +16,8 @@ COMPILEOPT=--pause
 all:
 
 # collect files to be maintained
-EDITFILES=$(filter-out src contrib %.bak,$(wildcard *) \
-                             $(shell find src -type f -maxdepth 1) \
+EDITFILES=$(filter-out flist src contrib %.bak,$(wildcard *) \
+                             $(shell find src -maxdepth 1 -type f) \
                              $(shell find contrib -type f))
 
 flist: Makefile $(EDITFILES)

src/libs/libdatrwxx/aalibdatrwxx.cc

+/*! \file aalibdatrwxx.cc
+ * \brief libdatrwxx version string (implementation)
+ * 
+ * ----------------------------------------------------------------------------
+ * 
+ * \author Thomas Forbriger
+ * \date 05/07/2016
+ * 
+ * libdatrwxx version string (implementation)
+ */
+#define DATRW_AALIBDATRWXX_CC_VERSION \
+  "DATRW_AALIBDATRWXX_CC   V1.0"
+
+#include <datrwxx/aalibdatrwxx.h>
+
+namespace datrw {
+
+  const char* const libversion="libdatrwxx (version 2016-07-05)";
+
+} // namespace datrw
+
+/* Copyright (c) 2016 by Thomas Forbriger (BFO Schiltach) 
+ *
+ * ----
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version. 
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+ * ----
+ *
+ * REVISIONS and CHANGES 
+ *  - 05/07/2016   V1.0   Thomas Forbriger
+ * 
+ * ============================================================================
+ */
+
+/* ----- END OF aalibdatrwxx.cc ----- */

src/libs/libdatrwxx/aalibdatrwxx.h

+/*! \file aalibdatrwxx.h
+ * \brief libdatrwxx version string (prototypes)
+ * 
+ * ----------------------------------------------------------------------------
+ * 
+ * \author Thomas Forbriger
+ * \date 05/07/2016
+ * 
+ * libdatrwxx version string (prototypes)
+ * 
+ * Copyright (c) 2016 by Thomas Forbriger (BFO Schiltach) 
+ * 
+ *
+ * ----
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version. 
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+ * ----
+ *
+ * REVISIONS and CHANGES 
+ *  - 05/07/2016   V1.0   Thomas Forbriger
+ * 
+ * ============================================================================
+ */
+
+// include guard
+#ifndef DATRW_AALIBDATRWXX_H_VERSION
+
+#define DATRW_AALIBDATRWXX_H_VERSION \
+  "DATRW_AALIBDATRWXX_H   V1.0"
+
+namespace datrw {
+
+
+  /*! \brief Version string.
+   *
+   * This string can be used in output to identify the library and its version
+   * Please update this string upon implementation of new features or upon bug
+   * fixes.
+   */
+  extern const char* const libversion;
+
+} // namespace datrw
+
+#endif // DATRW_AALIBDATRWXX_H_VERSION (includeguard)
+
+/* ----- END OF aalibdatrwxx.h ----- */

src/libs/libdatrwxx/ascii.h

@@ -47,7 +47,7 @@ namespace datrw {
 
   /*! \brief internals of the ascii I/O module
    *
-   * \ingroup ascii
+   * \ingroup group_ascii
    */
   namespace ascii {
 
@@ -60,7 +60,7 @@ namespace datrw {
   
   /*! \brief class to read ascii data
    *
-   * \ingroup ascii
+   * \ingroup group_ascii
    */
   class iasciistream: public idatstream {
     public:
@@ -100,7 +100,7 @@ namespace datrw {
 
   /*! \brief class to write ascii data
    *
-   * \ingroup ascii
+   * \ingroup group_ascii
    */
   class oasciistream: public odatstream {
     public:

src/libs/libdatrwxx/ascii/asciiformat.cc

@@ -40,7 +40,7 @@
 namespace datrw {
 
   /*! \brief Format properties
-   * \ingroup ascii
+   * \ingroup group_ascii
    * @{
    */
   const bool ascii::isbinary=false;
@@ -53,7 +53,7 @@ namespace datrw {
 
 /*! \brief I/O module for ASCII data
  *
- * \defgroup ascii I/O module for ASCII data
+ * \defgroup group_ascii I/O module for ASCII data
  *
  * Lines of ASCII data files either start with 
  *   - a single hash \c #: these lines provide header data; see keywords below

src/libs/libdatrwxx/ascii/asciiheaderkeys.h

@@ -44,7 +44,7 @@ namespace datrw {
   namespace ascii {
 
   /*! \brief key for WID2 line header field
-   * \ingroup ascii
+   * \ingroup group_ascii
    * @{
    */
     extern const char* const keydate;
@@ -61,7 +61,7 @@ namespace datrw {
   /**@}*/
 
   /*! \brief key for SRCE line header field
-   * \ingroup ascii
+   * \ingroup group_ascii
    * @{
    */
     extern const char* const keySRCEdate;
@@ -73,7 +73,7 @@ namespace datrw {
   /**@}*/
 
   /*! \brief key for INFO line header field
-   * \ingroup ascii
+   * \ingroup group_ascii
    * @{
    */
     extern const char* const keyRECVX;
@@ -84,7 +84,7 @@ namespace datrw {
   /**@}*/
 
   /*! \brief key for DATA type header field
-   * \ingroup ascii
+   * \ingroup group_ascii
    * @{
    */
     extern const char* const keydata;
@@ -94,7 +94,7 @@ namespace datrw {
   /**@}*/
 
   /*! \brief format modifier key
-   * \ingroup ascii
+   * \ingroup group_ascii
    * @{
    */
     extern const char* const keynonfatal;

src/libs/libdatrwxx/ascii/iasciistream.cc

@@ -28,15 +28,18 @@
  *
  * 
  * REVISIONS and CHANGES 
- *  - 18/10/2011   V1.0   Thomas Forbriger
+ *  - 18/10/2011   V1.0   Thomas Forbriger (thof)
  *  - 12/06/2012   V1.1   settraceheader must not be called before actual
  *                        number of samples ist set
  *                        correction in skipseries()
+ *  - 08/07/2016   V1.2   thof: 
+ *                        - make correct use of new DATRW_report_assert
+ *                        - make correct use of new DATRW_nonfatal_assert
  * 
  * ============================================================================
  */
 #define DATRW_IASCIISTREAM_CC_VERSION \
-  "DATRW_IASCIISTREAM_CC   V1.0   "
+  "DATRW_IASCIISTREAM_CC   V1.2"
 
 #include<iomanip>
 #include<vector>
@@ -255,7 +258,7 @@ namespace datrw {
             if (key.length()==0)
             {
               DATRW_report_assert(key.length()>0,
-                                  "keyword is missing in header line",
+                                  "keyword is missing in header line\n" <<
                                   "input line: " << Mcurrentline << "\n" <<
                                   "key: " << key);
             }
@@ -268,7 +271,7 @@ namespace datrw {
               // was not recognoized
               DATRW_nonfatal_assert(Mnonfatal,
                                     false,
-                                    "iasciistream: header key not recognized",
+                                    "iasciistream: header key not recognized\n"
                                     "input line: " << Mcurrentline << "\n" <<
                                     "key: " << key);
             }
@@ -297,7 +300,7 @@ namespace datrw {
     namespace {
 
       /*! read a sequence of samples
-       * \ingroup ascii
+       * \ingroup group_ascii
        *
        * Read a sequence of samples being regarded as a contiguous trace.
        *
@@ -378,7 +381,7 @@ namespace datrw {
             DATRW_nonfatal_assert(nonfatal,
                                   (i==n),
                                   "readsamples (ASCII): "
-                                  "found less samples than expected",
+                                  "found less samples than expected\n"
                                   "expected: " << n << " " <<
                                   "found: " << i);
           }
@@ -388,7 +391,7 @@ namespace datrw {
       /*----------------------------------------------------------------------*/
 
       /*! read a sequence of samples
-       * \ingroup ascii
+       * \ingroup group_ascii
        *
        * Read a sequence of samples being regarded as a contiguous trace.
        * This function essential performs the correct type conversion after
@@ -532,7 +535,7 @@ namespace datrw {
     namespace {
 
       /*!
-       * \ingroup ascii
+       * \ingroup group_ascii
        * \todo
        * replace with formatmodifiers::ModifierHelp
        */
@@ -550,7 +553,7 @@ namespace datrw {
       /*----------------------------------------------------------------------*/
 
       /*!
-       * \ingroup ascii
+       * \ingroup group_ascii
        * \todo
        * replace with formatmodifiers::ModifierHelp
        */

src/libs/libdatrwxx/binary.h

@@ -48,14 +48,14 @@ namespace datrw {
 
   /*! \brief I/O module for binary data
    *
-   * \defgroup binary I/O module for binary data
+   * \defgroup group_binary I/O module for binary data
    */
 
   /*----------------------------------------------------------------------*/
 
   /*! \brief internals of the binary I/O module
    *
-   * \ingroup binary
+   * \ingroup group_binary
    */
   namespace binary {
 
@@ -63,16 +63,16 @@ namespace datrw {
     extern const char* const streamID;
 
     /*! \brief magic number to identify file type and bytesex
-     * \ingroup binary
+     * \ingroup group_binary
      */
     extern const char* const magic;
     /*! \brief a version number for files - just in case
-     * \ingroup binary
+     * \ingroup group_binary
      */
     extern const short version;
 
     /*! \brief indicate file or trace properties
-     * \ingroup binary
+     * \ingroup group_binary
      */
     enum Eflags {
       Fsrce=   (1<<0), //!< trace has SRCE header
@@ -84,11 +84,11 @@ namespace datrw {
     }; // enum Eflags
 
     /*! \brief abort if file flags are inconsistent
-     * \ingroup binary
+     * \ingroup group_binary
      */
     void checkfileflags(const char& flags);
     /*! \brief abort if trace flags are inconsistent
-     * \ingroup binary
+     * \ingroup group_binary
      */
     void checktraceflags(const char& flags);
 
@@ -98,7 +98,7 @@ namespace datrw {
   
   /*! \brief class to read binary data
    *
-   * \ingroup binary
+   * \ingroup group_binary
    */
   class ibinarystream: public idatstream {
     public:
@@ -125,7 +125,7 @@ namespace datrw {
 
   /*! \brief class to write binary
    *
-   * \ingroup binary
+   * \ingroup group_binary
    */
   class obinarystream: public odatstream {
     public:

src/libs/libdatrwxx/binary/binary.cc

@@ -41,7 +41,7 @@
 namespace datrw {
 
   /*! \brief Format properties
-   * \ingroup binary
+   * \ingroup group_binary
    * @{
    */
   const bool binary::isbinary=false;

src/libs/libdatrwxx/binary/ibinarystream.cc

@@ -154,7 +154,7 @@ namespace datrw {
                      typename aff::Series<T>& series,
                      const char& flags)
         {
-          typedef typename aff::Series<T> Tinseries;
+          // typedef typename aff::Series<T> Tinseries;
           if (flags & datrw::binary::Fdouble)
           {
             Tdseries inseries;

src/libs/libdatrwxx/binary/ibinstream.h

@@ -51,7 +51,7 @@ namespace datrw {
   namespace binary {
 
     /*! \brief stream like class for binary input of basic types and classes
-     * \ingroup binary
+     * \ingroup group_binary
      */
     class ibinstream {
       public:
@@ -85,7 +85,7 @@ namespace datrw {
     /*----------------------------------------------------------------------*/
 
     /*! \brief input operator for basic types and classes
-     * \ingroup binary
+     * \ingroup group_binary
      */
     template<class C>
       ibinstream& operator>>(ibinstream& ibs, C& v)

src/libs/libdatrwxx/binary/obinstream.h

@@ -51,7 +51,7 @@ namespace datrw {
   namespace binary {
 
     /*! \brief binary output for basic types and classes
-     * \ingroup binary
+     * \ingroup group_binary
      */
     class obinstream {
       public:
@@ -81,7 +81,7 @@ namespace datrw {
     /*----------------------------------------------------------------------*/
 
     /*! \brief output operator for basic types and classes
-     * \ingroup binary
+     * \ingroup group_binary
      */
     template<class C>
       obinstream& operator<<(obinstream& obs, const C& v)

src/libs/libdatrwxx/bonjer.h

@@ -54,7 +54,7 @@ namespace datrw {
 
   /*! \brief input stream to read seismic data provided by K. Bonjer
    *
-   * \ingroup bonjer
+   * \ingroup group_bonjer
    *
    * The concept is based on SFF data contents and we will make use of SFF
    * structures.

src/libs/libdatrwxx/bonjer/ibonjerstream.cc

@@ -45,7 +45,7 @@ namespace datrw {
 
   //@{
   /*! \brief Format properties
-   * \ingroup bonjer
+   * \ingroup group_bonjer
    */
   const bool bonjer::isbinary=false;
   const char* const bonjer::streamID="bonjer";

src/libs/libdatrwxx/bonjer/readbonjer.h

@@ -46,12 +46,12 @@ namespace datrw {
 
   /*! \brief all functions, classes, etc. to read K. Bonjers data format
    *
-   * \defgroup bonjer Reading module for: file format defined by K. Bonjer
+   * \defgroup group_bonjer Reading module for: file format defined by K. Bonjer
    */
 
   /*! \brief all functions, classes, etc. to read K. Bonjers data format
    *
-   * \ingroup bonjer
+   * \ingroup group_bonjer
    */
   namespace bonjer {
 

src/libs/libdatrwxx/datwrite.cc

@@ -31,11 +31,12 @@
  *  - 11/04/2006   V1.0   Thomas Forbriger
  *  - 01/04/2011   V1.1   do not clear Mhassrce upon writing the file header
  *  - 07/06/2011   V1.2   promise constness of series samples
+ *  - 08/07/2016   V1.3   make correct use of new DATRW_report_assert
  * 
  * ============================================================================
  */
 #define DATRW_DATWRITE_CC_VERSION \
-  "DATRW_DATWRITE_CC   V1.2"
+  "DATRW_DATWRITE_CC   V1.3"
 
 #include<fstream>
 #include <datrwxx/datwrite.h>
@@ -103,11 +104,11 @@ namespace datrw {
     if (Mheaderflushed)
     {
       DATRW_report_assert(this->handlestracefree(),
-                          "file format cannot handle trace FREE data",
+                          "file format cannot handle trace FREE data\n" <<
                           "FREE data will be dropped silently");
     } else {
       DATRW_report_assert(this->handlesfilefree(),
-                          "file format cannot handle file FREE data",
+                          "file format cannot handle file FREE data\n" <<
                           "FREE data will be dropped silently");
     }
     Mfreeset=true;
@@ -128,7 +129,7 @@ namespace datrw {
   void odatstream::setinfo(const sff::INFO& info) 
   {
     DATRW_report_assert(this->handlesinfo(),
-                        "file format cannot handle INFO data",
+                        "file format cannot handle INFO data\n" 
                         "INFO data will be dropped silently");
     Minfoset=true;
     Minfo=info;
@@ -139,7 +140,7 @@ namespace datrw {
   void odatstream::setsrce(const sff::SRCE& srce) 
   {
     DATRW_report_assert(this->handlessrce(),
-                        "file format cannot handle SRCE data",
+                        "file format cannot handle SRCE data\n"
                         "SRCE data will be dropped silently");
     Msrceset=true;
     Msrce=srce;

src/libs/libdatrwxx/debug.h

@@ -62,7 +62,7 @@
  *
  * The macro can be used in the argument \par M of DATRW_debug
  */
-#define DATRW_value(V)  #V << ": " << V
+#define DATRW_value(V)  #V << "=" << V
 
 #endif // DATRW_DEBUG_H_VERSION (includeguard)
 

src/libs/libdatrwxx/doxygen.txt

@@ -70,6 +70,8 @@ namespace datrw {
     - \subpage page_writing_howto
     - \subpage page_writing_operation
 \subsubsection subsubsec_main_others_programmers For library maintainers and programmers
+  Upon implementing new features update the version string
+  datrw::libversion in \ref aalibdatrwxx.cc
     - \subpage page_implement_istream
     - \subpage page_implement_ostream
     - \subpage page_modifiers
@@ -609,7 +611,7 @@ The operators are provided in namespace ::datrw.
 
   \sa datrw::iseifestream::iseifestream(),
       datrw::oseifestream::oseifestream(),
-      \ref formatmodifiers,
+      \ref group_formatmodifiers,
       libdatrwxxtests.cc
 
   \date 09/2011

src/libs/libdatrwxx/doxygen_utilities.txt

@@ -23,29 +23,29 @@
   \note
     This page is still under construction.
 
-  \section sec_util_formatmodifiers 
+  \section sec_util_formatmodifiers Format modifiers
 
-    \sa \ref formatmodifiers
+    \sa \ref group_formatmodifiers
 
-  \section sec_util_datatypes 
+  \section sec_util_datatypes Data types
 
     \sa \ref datrw::datatypes
     \sa datatypes.h
 
-  \section sec_util_properties
+  \section sec_util_properties Properties
 
     \sa \subpage page_properties
-    \sa \ref properties
+    \sa \ref group_properties
 
-  \section sec_util_bytesex
+  \section sec_util_bytesex Bytesex
 
     \sa \ref group_bytesex
 
-  \section sec_util_error
+  \section sec_util_error Error handling
 
     \sa \ref group_error
 
-  \section sec_util_reservoir
+  \section sec_util_reservoir Time series reservoir
 
     \sa reservoir.h