cfl_helper.hGo 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 |