cfl_helper.h

Go to the documentation of this file.
00001 /** @file cfl_helper.h   Helper functions */
00002 
00003 /* FAU Discrete Event Systems Library (libfaudes)
00004 
00005    Copyright (C) 2006  Bernd Opitz
00006    Copyright (C) 2008-2010 Thomas Moor
00007    Exclusive copyright is granted to Klaus Schmidt
00008 
00009    This library is free software; you can redistribute it and/or
00010    modify it under the terms of the GNU Lesser General Public
00011    License as published by the Free Software Foundation; either
00012    version 2.1 of the License, or (at your option) any later version.
00013 
00014    This library is distributed in the hope that it will be useful,
00015    but WITHOUT ANY WARRANTY; without even the implied warranty of
00016    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00017    Lesser General Public License for more details.
00018 
00019    You should have received a copy of the GNU Lesser General Public
00020    License along with this library; if not, write to the Free Software
00021    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA */
00022 
00023 
00024 #ifndef FAUDES_HELPER_H
00025 #define FAUDES_HELPER_H
00026 
00027 #include "cfl_definitions.h"
00028 #include "cfl_platform.h"
00029 #include "cfl_exception.h"
00030 
00031 namespace faudes {
00032 
00033 // forward
00034 class Type;
00035 
00036 /**
00037  * integer to string
00038  * 
00039  * @param number
00040  *   integer
00041  *
00042  * @return
00043  *   string
00044  */
00045 std::string ToStringInteger(long int number);
00046 
00047 
00048 /**
00049  * integer to string base 16
00050  * 
00051  * @param number
00052  *   integer
00053  *
00054  * @return
00055  *   string
00056  */
00057 std::string ToStringInteger16(long int number);
00058 
00059 /**
00060  * float to string 
00061  * 
00062  * @param number
00063  *   double
00064  *
00065  * @return
00066  *   string
00067  */
00068 std::string ToStringFloat(double number);
00069 
00070 
00071 /**
00072  * Fill string with spaces up to a given length if length of the string
00073  * is smaller than given length parameter.
00074  *
00075  * @param rString
00076  *   string
00077  * @param len
00078  *   Minimum number of charakters in string
00079  *
00080  * @return
00081  *   Expanded string
00082  */
00083 std::string ExpandString(const std::string& rString, unsigned int len);
00084 
00085 /**
00086  * Limit length of string, return head and tail of string
00087  *
00088  * @param rString
00089  *   string
00090  * @param len
00091  *   Maximum number of charakters in string (approx)
00092  *
00093  * @return
00094  *   Collapsed string
00095  */
00096  std::string CollapsString(const std::string& rString, unsigned int len= FD_MAXCONTAINERNAME);
00097 
00098 
00099 /**
00100  * Convert a string to Idx
00101  *
00102  * @param rString
00103  *   string to convert
00104  *
00105  * @return 
00106  *   Idx
00107  *
00108  * @exception
00109  *   Idx overflow (id 600)
00110  */
00111 Idx ToIdx(const std::string& rString);
00112 
00113 /**
00114  * Substitute in string
00115  *
00116  * @param rString
00117  *   Source string to substitute
00118  * @param rFrom
00119  *   String to match
00120  * @param rTo
00121  *   Replacement to fill in 
00122  * @return 
00123  *   Result string
00124  *
00125  */
00126 std::string StringSubstitute(const std::string& rString,const std::string& rFrom,const std::string& rTo);
00127    
00128 
00129 
00130 /**
00131  * Return FAUDES_VERSION as std::string
00132  *
00133  * @return 
00134  *   std::string with FAUDES_VERSION
00135  */
00136 std::string VersionString();
00137 
00138 /**
00139  * Return FAUDES_PLUGINS as std::string
00140  *
00141  * @return 
00142  *   std::string with FAUDES_VERSION
00143  */
00144 std::string PluginsString();
00145 
00146 /**
00147  * Return contributors as std::string
00148  *
00149  * @return 
00150  *   std::string 
00151  */
00152 std::string ContributorsString();
00153 
00154 
00155 /**
00156  * Convenience function: process dot file
00157  * to graphics output.  If no output format is given,
00158  * try to guess from filename extension. 
00159  *
00160  * @param rDotFile
00161  *   name of dot file
00162  * @param rOutFile
00163  *   name of graphics file 
00164  * @param rOutFormat
00165  *   graphics format eg "png", "jpg"
00166  * @param rDotExec
00167  *   path/name of executable
00168  *
00169  * @exception Exception
00170  *   - error in systemcall (id 3)
00171  *   - unkown format (id 3)
00172  *
00173  */
00174 void ProcessDot(const std::string& rDotFile, const std::string& rOutFile, 
00175   const std::string& rOutFormat = "", const std::string& rDotExec = "dot");
00176 
00177 
00178 /**
00179  * Create a temp file, length 0
00180  *
00181  * @return
00182  *   Name of temp file
00183  */
00184 std::string CreateTempFile(void);
00185 
00186 
00187 /**
00188  * Delete a file
00189  *
00190  * @param rFileName
00191  *   Name of file to delete
00192  */
00193 bool RemoveFile(const std::string& rFileName);
00194 
00195 /**
00196  * Std dir-separator.
00197  * @return
00198  *   Separator as one-char string
00199  */
00200 const std::string& PathSeparator(void);
00201 
00202 /**
00203  * Extract directory from full path.
00204  *
00205  * @param rFullPath
00206  *   Full name of file eg "/home/friend/data/generator.gen"
00207  * @return
00208  *   Directory eg "/home/friend/data"
00209  */
00210 std::string ExtractDirectory(const std::string& rFullPath);
00211 
00212 /**
00213  * Extract file name from full path.
00214  *
00215  * @param rFullName
00216  *   Full path of file eg "/home/friend/data/generator.gen"
00217  * @return
00218  *   Filename "generator.gen"
00219  */
00220 std::string ExtractFilename(const std::string& rFullName);
00221 
00222 /**
00223  * Extract file name from full path. This version also
00224  * remove the last suffix.
00225  *
00226  * @param rFullName
00227  *   Full path of file eg "/home/friend/data/generator.gen"
00228  * @return
00229  *   Filename "generator"
00230  */
00231 std::string ExtractBasename(const std::string& rFullName);
00232 
00233 /**
00234  * Extract file name from full path. This version also
00235  * remove the last suffix.
00236  *
00237  * @param rFullName
00238  *   Full path of file eg "/home/friend/data/generator.gen"
00239  * @return
00240  *   Extension "gen"
00241  */
00242 std::string ExtractExtension(const std::string& rFullName);
00243 
00244 /**
00245  * Construct full path from directory and filename.
00246  *
00247  * @param rDirectory
00248  *   Directory eg "/home/friend/data"
00249  * @param rFileName
00250  *   File eg "generator.gen"
00251  * @return
00252  *   Path eg "/home/friend/data/generator.gen"
00253  */
00254 std::string PrependDirectory(const std::string& rDirectory, const std::string& rFileName);
00255 
00256 /**
00257  * Test existence of file
00258  *
00259  * @param rFilename
00260  *   Name of file to test
00261  * @return
00262  *   True <> can open file for reading
00263  */
00264 bool FileExists(const std::string& rFilename);
00265 
00266 /**
00267  * Delete  file
00268  *
00269  * @param rFilename
00270  *   Name of file to delete
00271  * @return
00272  *   True <> could delete the file
00273  */
00274 bool FileDelete(const std::string& rFilename);
00275 
00276 /**
00277  * Copy  file
00278  *
00279  * @param rFromFile
00280  *   Name of source file 
00281  * @param rToFile
00282  *   Name of dest file
00283  * @return
00284  *   True <> operation ok
00285  */
00286 bool FileCopy(const std::string& rFromFile, const std::string& rToFile);
00287 
00288 /**
00289  * Test existence of directory
00290  *
00291  * @param rDitectory
00292  *   Name of file to test
00293  * @return
00294  *   True <> can open directory for reading
00295  */
00296 bool DirectoryExists(const std::string& rDirectory);
00297 
00298 
00299 /**
00300  * Read the contents of the specified directors.
00301  *
00302  * @param rDirectory
00303  *   Directory eg "/home/friend/data"
00304  * @return
00305  *   List of files, e.g. "gen1.gen gen2.gen data subdir"
00306  */
00307 std::set< std::string > ReadDirectory(const std::string& rDirectory);
00308 
00309 
00310 /**
00311  * Console Out
00312  *
00313  * All console out messages (errors, progress report etc) are
00314  * meant to use the global ConsoleOut instance gConsoleOut, presumably
00315  * using the convenience macro FAUDES_WRITE_CONSOLE(). The default ConsoleOut::G()
00316  * provides optional redirection to a named file by 
00317  * G()->ConsoleOut.ToFile("filename"). 
00318  * 
00319  * libFAUDES applications can use this construct to grab all
00320  * console output by 1) deriving a specialised class from ConsoleOut and 2) 
00321  * redirection by ConsoleOut::G()->Redirect(derived_class_instance).
00322  */
00323 class ConsoleOut {
00324 public:
00325   /** Acess static instance */
00326   static ConsoleOut* G(void);
00327   /** Write a std::string message (optional progress report) */
00328   virtual void Write(const std::string& message,long int cntnow=0, long int cntdone=0);
00329   /** Redirect to file */
00330   void ToFile(const std::string& filename);
00331   /** Query filename */
00332   const std::string& Filename(void) { return mFilename;}; 
00333   /** Redirect */
00334   void Redirect(ConsoleOut* out);
00335   /** Mute */
00336   void Mute(bool on) {mMute=on;};
00337   bool Mute() { return mMute;};
00338 protected:
00339   /** Constructor */
00340   ConsoleOut(void);
00341   /** Destructor */
00342   virtual ~ConsoleOut(void);
00343   /** Writing hook. Re-implement this function in order to grab all output */
00344   virtual void DoWrite(const std::string& message,long int cntnow=0, long int cntdone=0);
00345 private:
00346   /** Private output stream */
00347   std::ofstream* pStream;
00348   /** Private record file name */
00349   std::string mFilename;
00350   /** Mute flag */
00351   bool mMute;
00352   /** Redirect */
00353   ConsoleOut* pInstance;
00354   /** Private static instance */
00355   static ConsoleOut* smpInstance;
00356 };
00357 
00358  
00359 /**
00360  * Debugging counter. Counts items as specified by the type string and reports
00361  * sums on exit. You must define the macro FAUDES_DEBUG_CODE to get a report.
00362  *
00363  * Technical note: we use the somewhat winded static member construct to
00364  * guarantee that our member variables have been constructed befor actual
00365  * counting occurs. This is neccessary since some faudes types might have a
00366  * static instance and, hence, may be consructed rather early. 
00367  *
00368  */
00369 class ObjectCount {
00370  public:
00371   static void Inc(const std::string& rTypeName);
00372   static void Dec(const std::string& rTypeName);
00373   static void Init(void);
00374   static std::map< std::string, long int >* mspMax;
00375   static std::map< std::string, long int >* mspCount;
00376  private:
00377   static bool msDone;
00378   ObjectCount(void);
00379 };
00380 
00381 
00382 /**
00383  * Test Protocol. 
00384  * Sets the filename for the test protocol by 
00385  * - removing any path specififucation,
00386  * - replacing "." by "_",
00387  * - appending ".prot", and finaly
00388  * - prepending "tmp_".
00389  * The function returns the filename except for the
00390  * "tmp_" prefix. The latter is considered the nominal
00391  * protocol output (aka reference protocol).
00392  * 
00393  * Note: only the first invocation of this functions actually sets
00394  * the protocol file. Further invocations are ignored, but can be
00395  * used to query the reference protocol.
00396  * 
00397  * @param rSource
00398  *   Source file to protocol
00399  * @return
00400  *   Filename with nominal protocol.
00401  *
00402  */
00403 std::string TestProtocol(const std::string& rSource);  
00404 
00405 
00406 /**
00407  * Test Protocol. 
00408  * This function dumps the specified data to the protocol file for
00409  * the purpose of later comparison with a refernce value.
00410  * If the protocol file has not been set up, this
00411  * function does nothing; see also TestProtocol(const std::string&.  
00412  * 
00413  * @param rMessage
00414  *   Informal identifyer of the test
00415  * @param rData
00416  *   Formal result of the test case
00417  * @param core
00418  *   Whether to record full token io or statistics only.
00419  *
00420  */
00421 void TestProtocol(const std::string& rMessage, const Type& rData, bool core=false); 
00422 
00423 /**
00424  * Test Protocol. 
00425  * Specialized version for boolean test data. 
00426  * See also TestProtocol(const std::string&, const Type&, bool);
00427  * 
00428  * @param rMessage
00429  *   Informal identifyer of the test
00430  * @param data
00431  *   Test data
00432  *
00433  */
00434 void TestProtocol(const std::string& rMessage, bool data); 
00435 
00436 /**
00437  * Test Protocol. 
00438  * Specialized version for integer test data. 
00439  * See also TestProtocol(const std::string&, const Type&, bool);
00440  * 
00441  * @param rMessage
00442  *   Informal identifyer of the test
00443  * @param data
00444  *   Test data
00445  *
00446  */
00447 void TestProtocol(const std::string& rMessage, long int data); 
00448 
00449 
00450 /**
00451  * Test Protocol. 
00452  * Specialized version for string data. 
00453  * See also TestProtocol(const std::string&, const Type&, bool);
00454  * 
00455  * @param rMessage
00456  *   Informal identifyer of the test
00457  * @param data
00458  *   Test data
00459  *
00460  */
00461  void TestProtocol(const std::string& rMessage, const std::string& data); 
00462 
00463 
00464 /**
00465  * Test Protocol. 
00466  * Perform a comparison of the recent protocol file and the
00467  * corresponding reference. Returns true if the test passes.
00468  *
00469  * Note: this function closes the current protocol.
00470  *
00471  * @return 
00472  *    True <=> test past
00473  */
00474 bool TestProtocol(void);
00475 
00476 
00477 /** Test protocol record macro */
00478 #define FAUDES_TEST_DUMP(mes,dat) { std::stringstream sstr; sstr << \
00479   mes << " [at " << __FILE__ << ":" << __LINE__ << "]" ; \
00480   TestProtocol(__FILE__); TestProtocol(sstr.str(),dat); }
00481 
00482 /** Test protocol diff macro */
00483 #define FAUDES_TEST_DIFF() { if(!TestProtocol()) { \
00484     FAUDES_WRITE_CONSOLE("FAUDES_TEST_DIFF: sensed test case error in " << __FILE__); exit(1);} }
00485 
00486 
00487 /** Algorithm loop callback 
00488  *
00489  * Set a callback function for libFAUDES algorithms. Applications
00490  * are meant to use this interface to terminate an algorithm on user
00491  * request. libFAUDES algorithms are meant to throw an execption when
00492  * the callback function returns true. See also void LoopCallback(void).
00493  *
00494  * @param pBreakFnct
00495  *
00496  */
00497  void LoopCallback(bool (*pBreakFnct)(void));
00498 
00499  /** Algorithm loop callback
00500   *
00501   * Calls the loop callback function and throws an exception if it
00502   * returns true. 
00503   *
00504   * @exception
00505   *   Break on appliation request (id 110)
00506   *
00507   */
00508  void LoopCallback(void);
00509 
00510 
00511 
00512 } // namespace faudes
00513 
00514 
00515 #endif
00516 

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen