cfl_utils.h
Go to the documentation of this file.
1 /** @file cfl_utils.h C-level utilities functions */
2 
3 /* FAU Discrete Event Systems Library (libfaudes)
4 
5  Copyright (C) 2006 Bernd Opitz
6  Copyright (C) 2008-2024 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_UTILS_H
25 #define FAUDES_UTILS_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 globally 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  * Return contributors as std::string
156  *
157  * @return
158  * std::string
159  */
160 extern FAUDES_API std::string BuildString();
161 
162 /**
163  * Convenience function: process dot file
164  * to graphics output. If no output format is given,
165  * try to guess from filename extension.
166  *
167  * @param rDotFile
168  * name of dot file
169  * @param rOutFile
170  * name of graphics file
171  * @param rOutFormat
172  * graphics format eg "png", "jpg"
173  * @param rDotExec
174  * path/name of executable
175  *
176  * @exception Exception
177  * - error in systemcall (id 3)
178  * - unkown format (id 3)
179  *
180  */
181 extern FAUDES_API void ProcessDot(const std::string& rDotFile, const std::string& rOutFile,
182  const std::string& rOutFormat = "", const std::string& rDotExec = "dot");
183 
184 
185 /**
186  * Create a temp file, length 0
187  *
188  * @return
189  * Name of temp file
190  */
191 extern FAUDES_API std::string CreateTempFile(void);
192 
193 
194 /**
195  * Std dir-separator.
196  * @return
197  * Separator as one-char string
198  */
199 extern FAUDES_API const std::string& PathSeparator(void);
200 
201 /**
202  * Extract directory from (full) path; i.e., remove the last
203  * separator and anything thereafer.
204  *
205  * @param rFullPath
206  * Full name of file eg (1) "/home/friend/data/generator.gen"
207  * Full name of file eg (2) "C:\data\project\generator.gen"
208  * @return
209  * Directory eg (1) "/home/friend/data"
210  * Directory eg (2) "C:\data\project"
211  */
212 extern FAUDES_API std::string ExtractDirectory(const std::string& rFullPath);
213 
214 /**
215  * Extract file name from full path.
216  *
217  * @param rFullName
218  * Full path of file eg "/home/friend/data/generator.gen"
219  * @return
220  * Filename "generator.gen"
221  */
222 extern FAUDES_API std::string ExtractFilename(const std::string& rFullName);
223 
224 /**
225  * Extract file basename from full path. This version also
226  * removes the last suffix.
227  *
228  * @param rFullName
229  * Full path of file eg "/home/friend/data/generator.gen"
230  * @return
231  * Filename "generator"
232  */
233 extern FAUDES_API std::string ExtractBasename(const std::string& rFullName);
234 
235 /**
236  * Extract extension from full path, i.e. ontain the last suffix.
237  *
238  * @param rFullName
239  * Full path of file eg "/home/friend/data/generator.gen"
240  * @return
241  * Extension "gen"
242  */
243 extern FAUDES_API std::string ExtractSuffix(const std::string& rFullName);
244 
245 /**
246  * Prepend one path before another. Specifically, insert a
247  * path seperator if necessary.
248  *
249  * @param rLeft
250  * Directory eg "/home/friend/data"
251  * @param rRight
252  * File eg "generator.gen"
253  * @return
254  * Path eg "/home/friend/data/generator.gen"
255  */
256 extern FAUDES_API std::string PrependPath(const std::string& rLeft, const std::string& rRight);
257 
258 /**
259  * Test existence of file
260  *
261  * @param rFilename
262  * Name of file to test
263  * @return
264  * True <> can open file for reading
265  */
266 extern FAUDES_API bool FileExists(const std::string& rFilename);
267 
268 /**
269  * Delete file
270  *
271  * @param rFilename
272  * Name of file to delete
273  * @return
274  * True <> could delete the file
275  */
276 extern FAUDES_API bool FileDelete(const std::string& rFilename);
277 
278 /**
279  * Copy file
280  *
281  * @param rFromFile
282  * Name of source file
283  * @param rToFile
284  * Name of dest file
285  * @return
286  * True <> operation ok
287  */
288 extern FAUDES_API bool FileCopy(const std::string& rFromFile, const std::string& rToFile);
289 
290 /**
291  * Test existence of directory
292  *
293  * @param rDirectory
294  * Name of file to test
295  * @return
296  * True <> can open directory for reading
297  */
298 extern FAUDES_API bool DirectoryExists(const std::string& rDirectory);
299 
300 
301 /**
302  * Read the contents of the specified directors.
303  *
304  * @param rDirectory
305  * Directory eg "/home/friend/data"
306  * @return
307  * List of files, e.g. "gen1.gen gen2.gen data subdir"
308  */
309 extern FAUDES_API std::set< std::string > ReadDirectory(const std::string& rDirectory);
310 
311 
312 /**
313  * Console Out
314  *
315  * All console out messages (errors, progress report etc) are
316  * meant to use the global ConsoleOut instance gConsoleOut, presumably
317  * using the convenience macro FAUDES_WRITE_CONSOLE(). The default ConsoleOut::G()
318  * provides optional redirection to a named file by G()->ConsoleOut.ToFile("filename").
319  * libFAUDES itself does not set/respect verbosity levels for its diagnostic
320  * output, this feature is implemented to support console applications.
321  *
322  * The main motivation of the entire construct is to support gui applications that may
323  * grab all console output by 1) deriving a specialised class from ConsoleOut and 2)
324  * redirection by ConsoleOut::G()->Redirect(derived_class_instance).
325  */
327 public:
328  /** Acess static instance */
329  static ConsoleOut* G(void);
330  /** Write a std::string message (optional progress report and verbosity) */
331  virtual void Write(const std::string& message,long int cntnow=0, long int cntdone=0, int verb=0);
332  /** Redirect to file */
333  void ToFile(const std::string& filename);
334  /** Query filename */
335  const std::string& Filename(void) { return mFilename;};
336  /** Redirect */
337  void Redirect(ConsoleOut* out);
338  /** Mute */
339  void Mute(bool on) {mMute=on;};
340  bool Mute() { return mMute;};
341  /** Verbosity */
342  void Verb(int verb) {mVerb=verb;};
343  int Verb() { return mVerb;};
344 protected:
345  /** Constructor */
346  ConsoleOut(void);
347  /** Destructor */
348  virtual ~ConsoleOut(void);
349  /** Writing hook. Re-implement this function in order to grab all output */
350  virtual void DoWrite(const std::string& message,long int cntnow=0, long int cntdone=0, int verb=0);
351 private:
352  /** Private output stream */
353  std::ofstream* pStream;
354  /** Private record file name */
355  std::string mFilename;
356  /** Mute flag */
357  bool mMute;
358  int mVerb;
359  /** Redirect */
361  /** Private static instance */
363 };
364 
365 
366 /**
367  * Debugging counter. Counts items as specified by the type string and reports
368  * sums on exit. You must define the macro FAUDES_DEBUG_CODE to get a report.
369  *
370  * Technical note: we use the somewhat winded static member construct to
371  * guarantee that our member variables have been constructed befor actual
372  * counting occurs. This is neccessary since some faudes types might have a
373  * static instance and, hence, may be consructed rather early.
374  *
375  */
377  public:
378  static void Inc(const std::string& rTypeName);
379  static void Dec(const std::string& rTypeName);
380  static void Init(void);
381  static std::map< std::string, long int >* mspMax;
382  static std::map< std::string, long int >* mspCount;
383  private:
384  static bool msDone;
385  ObjectCount(void);
386 };
387 
388 
389 /**
390  * Test Protocol.
391  * Sets the filename for the test protocol by
392  * - removing any path specififucation,
393  * - replacing "." by "_",
394  * - appending ".prot", and finaly
395  * - prepending "tmp_".
396  * The function returns the filename except for the
397  * "tmp_" prefix. The latter is considered the nominal
398  * protocol output (aka reference protocol).
399  *
400  * Note: only the first invocation of this functions actually sets
401  * the protocol file. Further invocations are ignored, but can be
402  * used to query the reference protocol.
403  *
404  * @param rSource
405  * Source file to protocol
406  * @return
407  * Filename with nominal protocol.
408  *
409  */
410 extern FAUDES_API std::string TestProtocol(const std::string& rSource);
411 
412 
413 /**
414  * Test Protocol.
415  * This function dumps the specified data to the protocol file for
416  * the purpose of later comparison with a refernce value.
417  * If the protocol file has not been set up, this
418  * function does nothing; see also TestProtocol(const std::string&.
419  *
420  * @param rMessage
421  * Informal identifyer of the test
422  * @param rData
423  * Formal result of the test case
424  * @param core
425  * Whether to record full token io or statistics only.
426  *
427  */
428 extern FAUDES_API void TestProtocol(const std::string& rMessage, const Type& rData, bool core=false);
429 
430 /**
431  * Test Protocol.
432  * Specialized version for boolean test data.
433  * See also TestProtocol(const std::string&, const Type&, bool);
434  *
435  * @param rMessage
436  * Informal identifyer of the test
437  * @param data
438  * Test data
439  *
440  */
441 extern FAUDES_API void TestProtocol(const std::string& rMessage, bool data);
442 
443 /**
444  * Test Protocol.
445  * Specialized version for integer test data.
446  * See also TestProtocol(const std::string&, const Type&, bool);
447  *
448  * @param rMessage
449  * Informal identifyer of the test
450  * @param data
451  * Test data
452  *
453  */
454 extern FAUDES_API void TestProtocol(const std::string& rMessage, long int data);
455 
456 
457 /**
458  * Test Protocol.
459  * Specialized version for string data.
460  * See also TestProtocol(const std::string&, const Type&, bool);
461  *
462  * @param rMessage
463  * Informal identifyer of the test
464  * @param data
465  * Test data
466  *
467  */
468 extern FAUDES_API void TestProtocol(const std::string& rMessage, const std::string& data);
469 
470 
471 /**
472  * Test Protocol.
473  * Perform a comparison of the recent protocol file and the
474  * corresponding reference. Returns true if the test passes.
475  *
476  * Note: this function closes the current protocol.
477  *
478  * @return
479  * True <=> test past
480  */
481 extern FAUDES_API bool TestProtocol(void);
482 
483 
484 /** Test protocol record macro ("mangle" filename for platform independance)*/
485 #define FAUDES_TEST_DUMP(mes,dat) { \
486  TestProtocol(__FILE__); \
487  std::string fname= __FILE__; \
488  std::replace(fname.begin(),fname.end(),'\\','/'); \
489  fname=ExtractFilename(fname); \
490  std::stringstream sstr; \
491  sstr << mes << " [at " << fname << ":" << __LINE__ << "]" ; \
492  TestProtocol(sstr.str(),dat); }
493 
494 /** Test protocol diff macro */
495 #define FAUDES_TEST_DIFF() { if(!TestProtocol()) { \
496  FAUDES_WRITE_CONSOLE("FAUDES_TEST_DIFF: sensed test case error in " << __FILE__); exit(1);} }
497 
498 
499 /** Algorithm loop callback
500  *
501  * Set a callback function for libFAUDES algorithms. Applications
502  * are meant to use this interface to terminate an algorithm on user
503  * request. libFAUDES algorithms are meant to throw an execption when
504  * the callback function returns true. See also void LoopCallback(void).
505  *
506  * @param pBreakFnct
507  *
508  */
509 extern FAUDES_API void LoopCallback(bool (*pBreakFnct)(void));
510 
511  /** Algorithm loop callback
512  *
513  * Calls the loop callback function and throws an exception if it
514  * returns true.
515  *
516  * @exception
517  * Break on appliation request (id 110)
518  *
519  */
520 extern FAUDES_API void LoopCallback(void);
521 
522 
523 
524 } // namespace faudes
525 
526 
527 #endif
528 
#define FD_MAXCONTAINERNAME
#define FAUDES_API
Definition: cfl_platform.h:80
ConsoleOut * pInstance
Definition: cfl_utils.h:360
std::ofstream * pStream
Definition: cfl_utils.h:353
static ConsoleOut * smpInstance
Definition: cfl_utils.h:362
const std::string & Filename(void)
Definition: cfl_utils.h:335
void Verb(int verb)
Definition: cfl_utils.h:342
void Mute(bool on)
Definition: cfl_utils.h:339
std::string mFilename
Definition: cfl_utils.h:355
static bool msDone
Definition: cfl_utils.h:384
static std::map< std::string, long int > * mspCount
Definition: cfl_utils.h:382
static std::map< std::string, long int > * mspMax
Definition: cfl_utils.h:381
uint32_t Idx
std::string VersionString()
Definition: cfl_utils.cpp:131
std::string ExtractDirectory(const std::string &rFullPath)
Definition: cfl_utils.cpp:272
void LoopCallback(bool pBreak(void))
Definition: cfl_utils.cpp:649
std::string PrependPath(const std::string &rLeft, const std::string &rRight)
Definition: cfl_utils.cpp:319
Idx ToIdx(const std::string &rString)
Definition: cfl_utils.cpp:100
void ProcessDot(const std::string &rDotFile, const std::string &rOutFile, const std::string &rOutFormat, const std::string &rDotExec)
Definition: cfl_utils.cpp:164
std::string CreateTempFile(void)
Definition: cfl_utils.cpp:221
bool FileCopy(const std::string &rFromFile, const std::string &rToFile)
Definition: cfl_utils.cpp:413
std::string PluginsString()
Definition: cfl_utils.cpp:136
std::string ExpandString(const std::string &rString, unsigned int len)
Definition: cfl_utils.cpp:80
std::string BuildString()
Definition: cfl_utils.cpp:147
bool FileDelete(const std::string &rFilename)
Definition: cfl_utils.cpp:408
std::string ToStringFloat(Float number)
Definition: cfl_utils.cpp:64
std::string ExtractFilename(const std::string &rFullPath)
Definition: cfl_utils.cpp:281
std::string ToStringInteger16(Int number)
Definition: cfl_utils.cpp:54
double Float
std::string ContributorsString()
Definition: cfl_utils.cpp:141
std::string ToStringInteger(Int number)
Definition: cfl_utils.cpp:43
std::set< std::string > ReadDirectory(const std::string &rDirectory)
Definition: cfl_utils.cpp:364
std::string StringSubstitute(const std::string &rString, const std::string &rFrom, const std::string &rTo)
Definition: cfl_utils.cpp:111
std::string ExtractBasename(const std::string &rFullPath)
Definition: cfl_utils.cpp:290
bool DirectoryExists(const std::string &rDirectory)
Definition: cfl_utils.cpp:348
std::string TestProtocol(const std::string &rSource)
Definition: cfl_utils.cpp:534
FAUDES_API const std::string & PathSeparator(void)
bool FileExists(const std::string &rFilename)
Definition: cfl_utils.cpp:401
std::string ExtractSuffix(const std::string &rFullPath)
Definition: cfl_utils.cpp:304
std::string CollapsString(const std::string &rString, unsigned int len)
Definition: cfl_utils.cpp:91
long int Int

libFAUDES 2.33c --- 2025.05.15 --- c++ api documentaion by doxygen