cfl_helper.h
Go to the documentation of this file.
1 /** @file cfl_helper.h Helper functions */
2 
3 /* FAU Discrete Event Systems Library (libfaudes)
4 
5  Copyright (C) 2006 Bernd Opitz
6  Copyright (C) 2008-2010 Thomas Moor
7  Exclusive copyright is granted to Klaus Schmidt
8 
9  This library is free software; you can redistribute it and/or
10  modify it under the terms of the GNU Lesser General Public
11  License as published by the Free Software Foundation; either
12  version 2.1 of the License, or (at your option) any later version.
13 
14  This library is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17  Lesser General Public License for more details.
18 
19  You should have received a copy of the GNU Lesser General Public
20  License along with this library; if not, write to the Free Software
21  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 
24 #ifndef FAUDES_HELPER_H
25 #define FAUDES_HELPER_H
26 
27 #include "cfl_definitions.h"
28 #include "cfl_platform.h"
29 #include "cfl_exception.h"
30 
31 namespace faudes {
32 
33 // forward
34 class Type;
35 
36 /**
37  * integer to string
38  *
39  * @param number
40  * integer
41  *
42  * @return
43  * string
44  */
45 extern FAUDES_API std::string ToStringInteger(Int number);
46 
47 
48 /**
49  * integer to string base 16
50  *
51  * @param number
52  * integer
53  *
54  * @return
55  * string
56  */
57 extern FAUDES_API std::string ToStringInteger16(Int number);
58 
59 /**
60  * float to string
61  *
62  * @param number
63  * double
64  *
65  * @return
66  * string
67  */
68 extern FAUDES_API std::string ToStringFloat(Float number);
69 
70 
71 /**
72  * Fill string with spaces up to a given length if length of the string
73  * is smaller than given length parameter.
74  *
75  * @param rString
76  * string
77  * @param len
78  * Minimum number of charakters in string
79  *
80  * @return
81  * Expanded string
82  */
83 extern FAUDES_API std::string ExpandString(const std::string& rString, unsigned int len);
84 
85 /**
86  * Limit length of string, return head and tail of string
87  *
88  * @param rString
89  * string
90  * @param len
91  * Maximum number of charakters in string (approx)
92  *
93  * @return
94  * Collapsed string
95  */
96 extern FAUDES_API std::string CollapsString(const std::string& rString, unsigned int len= FD_MAXCONTAINERNAME);
97 
98 
99 /**
100  * Convert a string to Idx
101  *
102  * @param rString
103  * string to convert
104  *
105  * @return
106  * Idx
107  *
108  * @exception
109  * Idx overflow (id 600)
110  */
111 extern FAUDES_API Idx ToIdx(const std::string& rString);
112 
113 /**
114  * Substitute in string
115  *
116  * @param rString
117  * Source string to substitute
118  * @param rFrom
119  * String to match
120  * @param rTo
121  * Replacement to fill in
122  * @return
123  * Result string
124  *
125  */
126 extern FAUDES_API std::string StringSubstitute(const std::string& rString,const std::string& rFrom,const std::string& rTo);
127 
128 
129 
130 /**
131  * Return FAUDES_VERSION as std::string
132  *
133  * @return
134  * std::string with FAUDES_VERSION
135  */
136 extern FAUDES_API std::string VersionString();
137 
138 /**
139  * Return FAUDES_PLUGINS as std::string
140  *
141  * @return
142  * std::string with FAUDES_VERSION
143  */
144 extern FAUDES_API std::string PluginsString();
145 
146 /**
147  * Return contributors as std::string
148  *
149  * @return
150  * std::string
151  */
152 extern FAUDES_API std::string ContributorsString();
153 
154 
155 /**
156  * Convenience function: process dot file
157  * to graphics output. If no output format is given,
158  * try to guess from filename extension.
159  *
160  * @param rDotFile
161  * name of dot file
162  * @param rOutFile
163  * name of graphics file
164  * @param rOutFormat
165  * graphics format eg "png", "jpg"
166  * @param rDotExec
167  * path/name of executable
168  *
169  * @exception Exception
170  * - error in systemcall (id 3)
171  * - unkown format (id 3)
172  *
173  */
174 extern FAUDES_API void ProcessDot(const std::string& rDotFile, const std::string& rOutFile,
175  const std::string& rOutFormat = "", const std::string& rDotExec = "dot");
176 
177 
178 /**
179  * Create a temp file, length 0
180  *
181  * @return
182  * Name of temp file
183  */
184 extern FAUDES_API std::string CreateTempFile(void);
185 
186 
187 /**
188  * Delete a file
189  *
190  * @param rFileName
191  * Name of file to delete
192  */
193 extern FAUDES_API bool RemoveFile(const std::string& rFileName);
194 
195 /**
196  * Std dir-separator.
197  * @return
198  * Separator as one-char string
199  */
200 extern FAUDES_API const std::string& PathSeparator(void);
201 
202 /**
203  * Extract directory from full path.
204  *
205  * @param rFullPath
206  * Full name of file eg "/home/friend/data/generator.gen"
207  * @return
208  * Directory eg "/home/friend/data"
209  */
210 extern FAUDES_API std::string ExtractDirectory(const std::string& rFullPath);
211 
212 /**
213  * Extract file name from full path.
214  *
215  * @param rFullName
216  * Full path of file eg "/home/friend/data/generator.gen"
217  * @return
218  * Filename "generator.gen"
219  */
220 extern FAUDES_API std::string ExtractFilename(const std::string& rFullName);
221 
222 /**
223  * Extract file name from full path. This version also
224  * removes the last suffix.
225  *
226  * @param rFullName
227  * Full path of file eg "/home/friend/data/generator.gen"
228  * @return
229  * Filename "generator"
230  */
231 extern FAUDES_API std::string ExtractBasename(const std::string& rFullName);
232 
233 /**
234  * Extract file name from full path. This version also
235  * remove the last suffix.
236  *
237  * @param rFullName
238  * Full path of file eg "/home/friend/data/generator.gen"
239  * @return
240  * Extension "gen"
241  */
242 extern FAUDES_API std::string ExtractExtension(const std::string& rFullName);
243 
244 /**
245  * Construct full path from directory and filename.
246  *
247  * @param rDirectory
248  * Directory eg "/home/friend/data"
249  * @param rFileName
250  * File eg "generator.gen"
251  * @return
252  * Path eg "/home/friend/data/generator.gen"
253  */
254 extern FAUDES_API std::string PrependDirectory(const std::string& rDirectory, const std::string& rFileName);
255 
256 /**
257  * Test existence of file
258  *
259  * @param rFilename
260  * Name of file to test
261  * @return
262  * True <> can open file for reading
263  */
264 extern FAUDES_API bool FileExists(const std::string& rFilename);
265 
266 /**
267  * Delete file
268  *
269  * @param rFilename
270  * Name of file to delete
271  * @return
272  * True <> could delete the file
273  */
274 extern FAUDES_API bool FileDelete(const std::string& rFilename);
275 
276 /**
277  * Copy file
278  *
279  * @param rFromFile
280  * Name of source file
281  * @param rToFile
282  * Name of dest file
283  * @return
284  * True <> operation ok
285  */
286 extern FAUDES_API bool FileCopy(const std::string& rFromFile, const std::string& rToFile);
287 
288 /**
289  * Test existence of directory
290  *
291  * @param rDitectory
292  * Name of file to test
293  * @return
294  * True <> can open directory for reading
295  */
296 extern FAUDES_API bool DirectoryExists(const std::string& rDirectory);
297 
298 
299 /**
300  * Read the contents of the specified directors.
301  *
302  * @param rDirectory
303  * Directory eg "/home/friend/data"
304  * @return
305  * List of files, e.g. "gen1.gen gen2.gen data subdir"
306  */
307 extern FAUDES_API std::set< std::string > ReadDirectory(const std::string& rDirectory);
308 
309 
310 /**
311  * Console Out
312  *
313  * All console out messages (errors, progress report etc) are
314  * meant to use the global ConsoleOut instance gConsoleOut, presumably
315  * using the convenience macro FAUDES_WRITE_CONSOLE(). The default ConsoleOut::G()
316  * provides optional redirection to a named file by
317  * G()->ConsoleOut.ToFile("filename").
318  *
319  * libFAUDES applications can use this construct to grab all
320  * console output by 1) deriving a specialised class from ConsoleOut and 2)
321  * redirection by ConsoleOut::G()->Redirect(derived_class_instance).
322  */
324 public:
325  /** Acess static instance */
326  static ConsoleOut* G(void);
327  /** Write a std::string message (optional progress report) */
328  virtual void Write(const std::string& message,long int cntnow=0, long int cntdone=0);
329  /** Redirect to file */
330  void ToFile(const std::string& filename);
331  /** Query filename */
332  const std::string& Filename(void) { return mFilename;};
333  /** Redirect */
334  void Redirect(ConsoleOut* out);
335  /** Mute */
336  void Mute(bool on) {mMute=on;};
337  bool Mute() { return mMute;};
338 protected:
339  /** Constructor */
340  ConsoleOut(void);
341  /** Destructor */
342  virtual ~ConsoleOut(void);
343  /** Writing hook. Re-implement this function in order to grab all output */
344  virtual void DoWrite(const std::string& message,long int cntnow=0, long int cntdone=0);
345 private:
346  /** Private output stream */
347  std::ofstream* pStream;
348  /** Private record file name */
349  std::string mFilename;
350  /** Mute flag */
351  bool mMute;
352  /** Redirect */
354  /** Private static instance */
356 };
357 
358 
359 /**
360  * Debugging counter. Counts items as specified by the type string and reports
361  * sums on exit. You must define the macro FAUDES_DEBUG_CODE to get a report.
362  *
363  * Technical note: we use the somewhat winded static member construct to
364  * guarantee that our member variables have been constructed befor actual
365  * counting occurs. This is neccessary since some faudes types might have a
366  * static instance and, hence, may be consructed rather early.
367  *
368  */
370  public:
371  static void Inc(const std::string& rTypeName);
372  static void Dec(const std::string& rTypeName);
373  static void Init(void);
374  static std::map< std::string, long int >* mspMax;
375  static std::map< std::string, long int >* mspCount;
376  private:
377  static bool msDone;
378  ObjectCount(void);
379 };
380 
381 
382 /**
383  * Test Protocol.
384  * Sets the filename for the test protocol by
385  * - removing any path specififucation,
386  * - replacing "." by "_",
387  * - appending ".prot", and finaly
388  * - prepending "tmp_".
389  * The function returns the filename except for the
390  * "tmp_" prefix. The latter is considered the nominal
391  * protocol output (aka reference protocol).
392  *
393  * Note: only the first invocation of this functions actually sets
394  * the protocol file. Further invocations are ignored, but can be
395  * used to query the reference protocol.
396  *
397  * @param rSource
398  * Source file to protocol
399  * @return
400  * Filename with nominal protocol.
401  *
402  */
403 extern FAUDES_API std::string TestProtocol(const std::string& rSource);
404 
405 
406 /**
407  * Test Protocol.
408  * This function dumps the specified data to the protocol file for
409  * the purpose of later comparison with a refernce value.
410  * If the protocol file has not been set up, this
411  * function does nothing; see also TestProtocol(const std::string&.
412  *
413  * @param rMessage
414  * Informal identifyer of the test
415  * @param rData
416  * Formal result of the test case
417  * @param core
418  * Whether to record full token io or statistics only.
419  *
420  */
421 extern FAUDES_API void TestProtocol(const std::string& rMessage, const Type& rData, bool core=false);
422 
423 /**
424  * Test Protocol.
425  * Specialized version for boolean test data.
426  * See also TestProtocol(const std::string&, const Type&, bool);
427  *
428  * @param rMessage
429  * Informal identifyer of the test
430  * @param data
431  * Test data
432  *
433  */
434 extern FAUDES_API void TestProtocol(const std::string& rMessage, bool data);
435 
436 /**
437  * Test Protocol.
438  * Specialized version for integer test data.
439  * See also TestProtocol(const std::string&, const Type&, bool);
440  *
441  * @param rMessage
442  * Informal identifyer of the test
443  * @param data
444  * Test data
445  *
446  */
447 extern FAUDES_API void TestProtocol(const std::string& rMessage, long int data);
448 
449 
450 /**
451  * Test Protocol.
452  * Specialized version for string data.
453  * See also TestProtocol(const std::string&, const Type&, bool);
454  *
455  * @param rMessage
456  * Informal identifyer of the test
457  * @param data
458  * Test data
459  *
460  */
461 extern FAUDES_API void TestProtocol(const std::string& rMessage, const std::string& data);
462 
463 
464 /**
465  * Test Protocol.
466  * Perform a comparison of the recent protocol file and the
467  * corresponding reference. Returns true if the test passes.
468  *
469  * Note: this function closes the current protocol.
470  *
471  * @return
472  * True <=> test past
473  */
474 extern FAUDES_API bool TestProtocol(void);
475 
476 
477 /** Test protocol record macro ("mangle" filename for platform independance)*/
478 #define FAUDES_TEST_DUMP(mes,dat) { \
479  TestProtocol(__FILE__); \
480  std::string fname= __FILE__; \
481  std::replace(fname.begin(),fname.end(),'\\','/'); \
482  fname=ExtractFilename(fname); \
483  std::stringstream sstr; \
484  sstr << mes << " [at " << fname << ":" << __LINE__ << "]" ; \
485  TestProtocol(sstr.str(),dat); }
486 
487 /** Test protocol diff macro */
488 #define FAUDES_TEST_DIFF() { if(!TestProtocol()) { \
489  FAUDES_WRITE_CONSOLE("FAUDES_TEST_DIFF: sensed test case error in " << __FILE__); exit(1);} }
490 
491 
492 /** Algorithm loop callback
493  *
494  * Set a callback function for libFAUDES algorithms. Applications
495  * are meant to use this interface to terminate an algorithm on user
496  * request. libFAUDES algorithms are meant to throw an execption when
497  * the callback function returns true. See also void LoopCallback(void).
498  *
499  * @param pBreakFnct
500  *
501  */
502 extern FAUDES_API void LoopCallback(bool (*pBreakFnct)(void));
503 
504  /** Algorithm loop callback
505  *
506  * Calls the loop callback function and throws an exception if it
507  * returns true.
508  *
509  * @exception
510  * Break on appliation request (id 110)
511  *
512  */
513 extern FAUDES_API void LoopCallback(void);
514 
515 
516 
517 } // namespace faudes
518 
519 
520 #endif
521 

libFAUDES 2.28a --- 2016.09.13 --- c++ api documentaion by doxygen