ALib C++ Library
Library Version: 2312 R0
Documentation generated by doxygen
tools.hpp
Go to the documentation of this file.
1 /** ************************************************************************************************
2  * \file
3  * This header file is part of the \aliblong. It does neither belong to a fileset, nor to a
4  * specific module of \alib, but is included in any \alibdist.
5  *
6  * \emoji :copyright: 2013-2023 A-Worx GmbH, Germany.
7  * Published under \ref mainpage_license "Boost Software License".
8  *
9  * \note
10  * To reduce complexity, this header is not shown in inclusion graphs of this documentation.
11  **************************************************************************************************/
12 #ifndef HPP_ALIB_TOOLS
13 #define HPP_ALIB_TOOLS 1
14 
15 #if !defined(HPP_ALIB_COMPILERS) && !defined(ALIB_DOX)
16 # include "alib/lib/compilers.hpp"
17 #endif
18 
19 #if !defined(HPP_ALIB_PLATFORMS) && !defined(ALIB_DOX)
20 # include "alib/lib/platforms.hpp"
21 #endif
22 
23 
24 //--------------------------------------------------------------------------------------------------
25 //----- Preprocessor tools
26 //--------------------------------------------------------------------------------------------------
27 
28 #if defined(ALIB_DOX)
29 # define ALIB_NSTRINGIFY(a)
30 # define ALIB_STRINGIFY(a)
31 #else
32 # define ALIB_STRINGIFY_X(a) A_CHAR( #a )
33 # define ALIB_STRINGIFY(a) ALIB_STRINGIFY_X(a)
34 # define ALIB_NSTRINGIFY_X(a) #a
35 # define ALIB_NSTRINGIFY(a) ALIB_NSTRINGIFY_X(a)
36 #endif
37 
38 #define ALIB_CONCAT(a,b) a ## b
39 
40 #if defined(__clang__)
41 # define ALIB_IDENTIFIER(prefix) ALIB_WARNINGS_IGNORE_RESERVED_IDENTIFIER \
42  ALIB_CONCAT(prefix, __LINE__) \
43  ALIB_WARNINGS_RESTORE
44 #else
45 # define ALIB_IDENTIFIER(prefix) ALIB_CONCAT(prefix, __LINE__)
46 #endif
47 
48 #define ALIB_EMPTY
49 
50 
51 #define ALIB_COMMA ,
52 #if ALIB_DEBUG
53 # define ALIB_COMMA_DBG ,
54 #else
55 # define ALIB_COMMA_DBG
56 #endif
57 
58 
59 // Macros for passing source code information
60 #if defined( __GNUC__ )
61 # define ALIB_CALLER __FILE__, __LINE__, __func__
62  //#define ALIB_CALLER __FILE__, __LINE__, __PRETTY_FUNCTION__
63 #elif defined ( _MSC_VER )
64 # define ALIB_CALLER __FILE__, __LINE__, __FUNCTION__
65  //#define ALIB_CALLER __FILE__, __LINE__, __FUNCSIG__
66 #else
67 # pragma message ("Unknown Platform in file: " __FILE__ )
68 #endif
69 
70 #if ALIB_DEBUG
71  #define ALIB_CALLER_PRUNED ALIB_CALLER
72  #define ALIB_CALLER_NULLED ALIB_CALLER
73 #else
74  #define ALIB_CALLER_PRUNED
75  #define ALIB_CALLER_NULLED nullptr, 0, nullptr
76 #endif
77 
78 
79 // Macros for doing "nicer" static_assert messages
80 #define ALIB_STATIC_ASSERT( CondVariable, Cond, Message ) \
81 { constexpr bool CondVariable= Cond; \
82  static_assert( CondVariable, Message ); } \
83 
84 #define ALIB_STATIC_DENY( CondVariable, Cond, Message ) \
85 { constexpr bool CondVariable= !(Cond); \
86  static_assert( CondVariable, Message ); } \
87 
88 
89 // #################################################################################################
90 // Debug Messages and Assertions
91 // #################################################################################################
92 #if ALIB_DEBUG
93 # if !defined (_ASSERT_H) && !defined(assert)
94 # include <assert.h>
95 # endif
96 
97 namespace aworx { namespace lib {
98 
99 /**
100  * Some \alib modules do not (must not) rely on
101  * \ref aworx::lib::results::Report "Report" /
102  * \alib{results,ReportWriter} mechanics. Therefore, this simple method is
103  * used for error handling in those portions of \alib that are exposed in such modules.<br>
104  * This method first checks if static function pointer
105  * \alib{DBG_SIMPLE_ALIB_MSG_PLUGIN} is set and if yes, passes the parameters
106  * to this method and exits.
107  * If the complete \alib distribution is used, method
108  * \alib{ALibDistribution::Bootstrap}
109  * sets this plug-in function to a custom one which passes the message(s) to a proper
110  * \ref aworx::lib::results::Report "ALib Report".
111  *
112  * Otherwise the method just writes to the standard output stream and then,
113  * if \p{type} equals \c 0, invokes <c>assert(0)</c>.
114  *
115  * @param file The source file of the message invocation.
116  * @param line The line number within \p{file}.
117  * @param method The method invoking this function.
118  * @param type The type of the message. The default implementation does not use this, other
119  * than invoking <c>assert(0)</c> in the case this parameter equals \c 0.
120  * @param topic The topic of the message.
121  * @param msg1 The first message string.
122  * @param msg2 Optional 2nd message string.
123  * @param msg3 Optional 3rd message string.
124  * @param msg4 Optional 4th message string.
125  * @param msg5 Optional 5th message string.
126  *
127  */
128 ALIB_API
129 extern void DbgSimpleALibMsg( const char* file, int line, const char* method,
130  int type,
131  const char* topic,
132  const char* msg1= nullptr,
133  const char* msg2= nullptr,
134  const char* msg3= nullptr,
135  const char* msg4= nullptr,
136  const char* msg5= nullptr );
137 
138 /**
139  * Overloaded version of
140  * \ref DbgSimpleALibMsg(const char*,int,const char*,int,const char*,const char*,const char*,const char*,const char*,const char*) "DbgSimpleALibMsg"
141  * which accepts one integral value and writes \p{msg} and \p{intValue} in sequence.
142  *
143  * @param file The source file of the message invocation.
144  * @param line The line number within \p{file}.
145  * @param method The method invoking this function.
146  * @param type The type of the message. The default implementation does not use this, other
147  * than invoking <c>assert(0)</c> in the case this parameter equals \c 0.
148  * @param topic The topic of the report.
149  * @param msg The message string.
150  * @param intValue An integer parameter (optional due to overload).
151  *
152  */
153 ALIB_API
154 extern void DbgSimpleALibMsg( const char* file, int line, const char* method,
155  int type,
156  const char* topic,
157  const char* msg,
158  const int intValue );
159 
160 /**
161  * This function pointer defaults to \c nullptr and may be set to replace function
162  * #DbgSimpleALibMsg.
163  * With the use of \alib_results, the module's bootstrap code (precisely method
164  * \alib{results,Results::bootstrap}) sets this pointer to a small method which creates an
165  * \alib{results,Report} on the default \alib{results,ReportWriter}.
166  *
167  * - \p{file}: Information about the scope of invocation.
168  * - \p{line}: Information about the scope of invocation.
169  * - \p{method}: Information about the scope of invocation.
170  * - \p{type}: The type of the message. As a convention, 0 is severe error, others are warning levels.
171  * - \p{qtyMsgs}: The number of messages passed.
172  * - \p{msgs}: The message strings.
173  */
174 extern void (*DBG_SIMPLE_ALIB_MSG_PLUGIN)( const char* file, int line, const char* method,
175  int type , const char* topic,
176  int qtyMsgs, const char** msgs );
177 
178 
179 }} // namespace [aworx::lib]
180 
181 #define ALIB_ERROR(...) { aworx::lib::DbgSimpleALibMsg( ALIB_CALLER_PRUNED, 0, __VA_ARGS__); }
182 #define ALIB_WARNING(...) { aworx::lib::DbgSimpleALibMsg( ALIB_CALLER_PRUNED, 1, __VA_ARGS__); }
183 #define ALIB_MESSAGE(...) { aworx::lib::DbgSimpleALibMsg( ALIB_CALLER_PRUNED, 2, __VA_ARGS__); }
184 #define ALIB_ASSERT(cond) { if(!(cond)) ALIB_ERROR( "Assertion Failed" ); }
185 #define ALIB_ASSERT_ERROR(cond, ...) { if(!(cond)) ALIB_ERROR( __VA_ARGS__ ); }
186 #define ALIB_ASSERT_WARNING(cond, ...) { if(!(cond)) ALIB_WARNING( __VA_ARGS__ ); }
187 #define ALIB_ASSERT_MESSAGE(cond, ...) { if(!(cond)) ALIB_MESSAGE( __VA_ARGS__ ); }
188 
189 #else // ALIB_DEBUG
190  #define ALIB_ERROR(...) {}
191  #define ALIB_WARNING(...) {}
192  #define ALIB_MESSAGE(...) {}
193  #define ALIB_ASSERT(cond) {}
194  #define ALIB_ASSERT_ERROR(cond, ...) {}
195  #define ALIB_ASSERT_WARNING(cond, ...) {}
196  #define ALIB_ASSERT_MESSAGE(cond, ...) {}
197 #endif
198 
199 #if ALIB_DEBUG
200  #define ALIB_ASSERT_RESULT_EQUALS( func, value ) { auto result= func; assert(result == value); ((void) result); }
201  #define ALIB_ASSERT_RESULT_NOT_EQUALS( func, value ) { auto result= func; assert(result != value); ((void) result); }
202  #define ALIB_ASSERT_RESULT_GREATER_THAN(func, value ) { auto result= func; assert(result > value); ((void) result); }
203  #define ALIB_ASSERT_RESULT_LESS_THAN( func, value ) { auto result= func; assert(result < value); ((void) result); }
204 #else
205  #define ALIB_ASSERT_RESULT_EQUALS( func, value ) { func; }
206  #define ALIB_ASSERT_RESULT_NOT_EQUALS( func, value ) { func; }
207  #define ALIB_ASSERT_RESULT_GREATER_THAN(func, value ) { func; }
208  #define ALIB_ASSERT_RESULT_LESS_THAN( func, value ) { func; }
209 #endif
210 
211 
212 // #################################################################################################
213 // Type De-mangling
214 // #################################################################################################
215 #if !defined (_TYPEINFO) && !defined(_TYPEINFO_)
216  #include <typeinfo>
217 #endif
218 
219 
220 #if ALIB_DEBUG
221 
222 namespace aworx { namespace lib {
223 
224 /** ********************************************************************************************
225  * Retrieves human readable names from C++ run-time type information.<br>
226  * This class is available only with debug builds of \alib.
227  **********************************************************************************************/
228 class DbgTypeDemangler
229 {
230  protected:
231  /** The translated name name. */
232  const char* name;
233 
234  public:
235  /** ************************************************************************************
236  * Constructor
237  * @param typeInfo The information struct on the C++ type.
238  **************************************************************************************/
239  ALIB_API
240  DbgTypeDemangler( const std::type_info& typeInfo );
241 
242  /** ************************************************************************************
243  * Destructor
244  **************************************************************************************/
245  ALIB_API
246  ~DbgTypeDemangler();
247 
248  /** ************************************************************************************
249  * Returns the demangled, human readable name of the type which was provided in the
250  * constructor.
251  * @return The demangled type name.
252  **************************************************************************************/
253  ALIB_API
254  const char* Get();
255 }; // class DbgTypeDemangler
256 
257 }} // namespace [aworx::lib]
258 
259 #endif // ALIB_DEBUG
260 
261 
262 #endif // HPP_ALIB_TOOLS
aworx::lib::DbgTypeDemangler
Definition: tools.hpp:228
aworx::lib::DbgTypeDemangler::Get
const ALIB_API char * Get()
aworx::lib::DbgSimpleALibMsg
ALIB_API void DbgSimpleALibMsg(const char *file, int line, const char *method, int type, const char *topic, const char *msg1=nullptr, const char *msg2=nullptr, const char *msg3=nullptr, const char *msg4=nullptr, const char *msg5=nullptr)
aworx::lib::DbgTypeDemangler::DbgTypeDemangler
ALIB_API DbgTypeDemangler(const std::type_info &typeInfo)
aworx::lib::DbgTypeDemangler::name
const char * name
Definition: tools.hpp:232
platforms.hpp
compilers.hpp
aworx::lib::DbgTypeDemangler::~DbgTypeDemangler
ALIB_API ~DbgTypeDemangler()
aworx
Definition: alox/alox.hpp:40
ALIB_API
#define ALIB_API
Definition: compilers.hpp:150
aworx::lib::DBG_SIMPLE_ALIB_MSG_PLUGIN
void(* DBG_SIMPLE_ALIB_MSG_PLUGIN)(const char *file, int line, const char *method, int type, const char *topic, int qtyMsgs, const char **msgs)
Definition: alib.cpp:106