|
ALib C++ Library
|
by |  |
|
|
ALib C++ Library
|
by | |
|
This is the reference documentation for preprocessor symbols that evaluate to true or false (precisely 1 or 0). Unless explicitly mentioned, the symbols may be passed to the compiler to overwrite their documented default value.
The following sections of this document lists macros that are not related to a specific ALib Module :
General Symbols
General Symbols Deduced By Headers
ALib Module Selection
Followed to this, module-specific symbols are documented:
Module ALox
Module Boxing
Module Characters
Module Memory
Module BaseCamp
Module Singletons
Module Strings
General Preprocessor Symbols | |
The following general symbols (aka symbols not related to distinct ALib Modules ) may be passed to the compiler: | |
| #define | ALIB_API_IS_DLL |
| #define | ALIB_API_NO_DLL |
| #define | ALIB_AVOID_ANALYZER_WARNINGS 1 |
| #define | ALIB_DEBUG |
| #define | ALIB_EXT_LIB_THREADS_AVAILABLE |
| #define | ALIB_GDB_PP_SUPPRESS_CHILDREN |
| #define | ALIB_GDB_PP_FIND_POINTER_TYPES |
| #define | ALIB_GTEST |
| #define | ALIB_PRECOMPILED_HEADER |
General Preprocessor Symbols Deduced By ALib Headers | |
The following general symbols (aka symbols not related to distinct ALib Modules ) are deduced by ALib headers and thus usually are not to be passed to the compiler.
| |
| #define | ALIB_DOX |
| #define | ALIB_CPP_STANDARD |
| #define | ALIB_GCC |
| #define | ALIB_SIZEOF_INTEGER |
| #define | ALIB_INTGAP_TYPE |
| #define | ALIB_SIZEOF_INTGAP |
| #define | ALIB_SIZEOF_LONGDOUBLE_REPORTED |
| #define | ALIB_SIZEOF_LONGDOUBLE_WRITTEN |
ALib Module Selection | |
|
This group of symbols determine the availability of different ALib Modules of the ALib Distribution used. The symbols are defined in header alib/alib.hpp which always is and has to be the first ALib header file included (directly or indirectly). If none of the symbols is passed to the compiler, this header file will define all to If a symbol is given as | |
| #define | ALIB_ALOX 1 |
| #define | ALIB_BITBUFFER 1 |
| #define | ALIB_BOXING 1 |
| #define | ALIB_CHARACTERS 1 |
| #define | ALIB_CLI 1 |
| #define | ALIB_CONFIGURATION 1 |
| #define | ALIB_ENUMS 1 |
| #define | ALIB_EXPRESSIONS 1 |
| #define | ALIB_FILES 1 |
| #define | ALIB_MONOMEM 1 |
| #define | ALIB_SINGLETONS 1 |
| #define | ALIB_STRINGS 1 |
| #define | ALIB_CAMP 1 |
| #define | ALIB_THREADS 1 |
| #define | ALIB_TIME 1 |
ALib Module ALox Feature Selection | |
|
This group of code selection symbols is defined with the use of module ALox and used to select the inclusion of log code. The symbols are seldom to be used by end-user code. Instead, the macros used for the log statements themselves (see debug logging macros and release logging macros.) are variably defined based on these symbols. | |
| #define | ALOX_DBG_LOG 1 |
| #define | ALOX_REL_LOG 1 |
| #define | ALOX_DBG_LOG_CI 1 |
| #define | ALOX_REL_LOG_CI 1 |
ALib Module Boxing Feature Selection | |
| #define | ALIB_FEAT_BOXING_BIJECTIVE_INTEGRALS 1 |
| #define | ALIB_FEAT_BOXING_BIJECTIVE_CHARACTERS 1 |
| #define | ALIB_FEAT_BOXING_BIJECTIVE_FLOATS 1 |
| #define | ALIB_DEBUG_BOXING 1 |
ALib Module Characters Feature Selection | |
| #define | ALIB_CHARACTERS_WIDE 1 |
| #define | ALIB_CHARACTERS_NATIVE_WCHAR |
| #define | ALIB_CHARACTERS_SIZEOF_WCHAR ALIB_SIZEOF_WCHAR_T |
ALib Module Memory Feature Selection | |
| #define | ALIB_DEBUG_MONOMEM 1 |
| #define | ALIB_DEBUG_ARRAY_COMPRESSION 1 |
ALib Module BaseCamp Feature Selection | |
| #define | ALIB_RESOURCES_OMIT_DEFAULTS 0 |
| #define | ALIB_DEBUG_RESOURCES 1 |
ALib Module Singletons Feature Selection | |
| #define | ALIB_FEAT_SINGLETON_MAPPED 1 |
ALib Module Strings Feature Selection | |
| #define | ALIB_FEAT_BOOST_REGEX 1 |
| #define | ALIB_DEBUG_STRINGS 1 |
| #define ALIB_ALOX 1 |
Denotes if module ALox is included in the ALib Distribution .
| #define ALIB_API_IS_DLL |
This compiler symbol has to be defined when compiling ALib as a DLL, and has to be undefined (or 0) when compiling user code that includes ALib header files.
If ALIB_API_NO_DLL is given, this symbol is ignored.
Definition at line 16 of file prepro.dox.
| #define ALIB_API_NO_DLL |
This compiler symbol has to be defined when compiling ALib classes directly into a project Windows/MSC (not using a DLL).
If given, ALIB_API_IS_DLL is ignored. If not given, ALIB_API_IS_DLL has to be set to 1 if the DLL is compiled, and to 0 if code that is using ALib residing in a DLL is compiled.
Definition at line 17 of file prepro.dox.
| #define ALIB_AVOID_ANALYZER_WARNINGS 1 |
| #define ALIB_BITBUFFER 1 |
Denotes if module ALib BitBuffer is included in the ALib Distribution .
| #define ALIB_BOXING 1 |
Denotes if module ALib Boxing is included in the ALib Distribution .
| #define ALIB_CAMP 1 |
Denotes if module ALib BaseCamp is included in the ALib Distribution .
| #define ALIB_CHARACTERS 1 |
Denotes if module ALib Characters is included in the ALib Distribution .
| #define ALIB_CHARACTERS_NATIVE_WCHAR |
If true, type wchar is equivalent to C++ built-in type wchar_t. Otherwise, wchar has a different width than wchar_t and equals to either char16_t or char32_t: If a compiler's defines wchar_t as a 2-byte integral, char32_t is chosen and char16_t if it is a 4-byte integral.
This symbol depends on operating system and compiler defaults and may be manipulated by passing symbol ALIB_CHARACTERS_SIZEOF_WCHAR with library compilation.
Note, that the use of this symbol to select code should be needed very seldom. Instead, it is advised to use "logical character" types and other provided helpers and macros that convert characters and string types transparently.
Definition at line 32 of file prepro.dox.
| #define ALIB_CHARACTERS_SIZEOF_WCHAR ALIB_SIZEOF_WCHAR_T |
Provides the with of ALib type wchar in bytes.
If not set, a compiler/platform-dependent default value is chosen.
If passed to the compiler, then type wchar will be set independent from the width of wchar_t, which is compiler dependent and symbol ALIB_CHARACTERS_NATIVE_WCHAR will be set accordingly.
If a value of 2 is given, then type wchar will be 2 bytes wide. Precisely, wchar will be equivalent to type wchar_t with compilers that define the latter as a 2-byte integral value and equivalent to type char16_t, if wchar_t is a 4-byte integral.
If a value of 2 is given, then type wchar will be 4 bytes wide. Precisely, wchar will be equivalent to type wchar_t with compilers that define the latter as a 4-byte integral value and equivalent to type char32_t, if wchar_t is a 2-byte integral.
Other values are not allowed.
| #define ALIB_CHARACTERS_WIDE 1 |
If false, type character is equivalent to C++ built-in type char. Otherwise, character equals the multi-byte character type wchar , which in turn is equivalent to either of wchar_t, char16_t or char32_t.
Note, that the use of this symbol to select code should be needed very seldom. Instead, it is advised to use "logical character" types and other provided helpers and macros that convert characters and string types transparently.
If the symbol is not externally set (passed to the compiler), the choice of the default character type is system dependent: On Windows OS, wide character strings are chosen, while on Unix-like OSes, narrow character strings are used by default.
| #define ALIB_CLI 1 |
Denotes if module ALib CLI is included in the ALib Distribution .
| #define ALIB_CONFIGURATION 1 |
Denotes if module ALib Configuration is included in the ALib Distribution .
| #define ALIB_CPP_STANDARD |
Symbol containing the C++ language standard used for compilation. Possible values are 17, 20 and 23.
For MSC and GNU GCC (and compatible compilers like Clang), this macro is automatically detected. For unknown compilers/toolchains, this symbol may be passed to the compiler.
Definition at line 19 of file prepro.dox.
| #define ALIB_DEBUG |
If true (1), plausibility checks and ALib assertions are enabled.
Definition at line 21 of file prepro.dox.
| #define ALIB_DEBUG_ARRAY_COMPRESSION 1 |
Selects code that reads back integral arrays after compression with class ArrayCompressor to check compression/decompression algorithms.
This symbol defaults to true in debug builds of the library.
Definition at line 43 of file prepro.dox.
| #define ALIB_DEBUG_BOXING 1 |
Selects extended debug code in module ALib Boxing .
If given as true in release builds, the symbol is redefined to false and a compiler pragma warning is printed.
Details on the features enabled by this symbol are given in chapter 12.7.1 Available Debug Objects And Fields of the Programmer's Manual of module ALib Boxing .
Definition at line 40 of file prepro.dox.
| #define ALIB_DEBUG_MONOMEM 1 |
Selects extended debug code in module ALib Monomem .
If given as true in release builds, the symbol is redefined to false and a compiler pragma warning is printed.
In particular, the following features become enabled:
The following debug fields and methods become available:
Definition at line 42 of file prepro.dox.
| #define ALIB_DEBUG_RESOURCES 1 |
Selects extended debug code in module ALib BaseCamp .
If given as true in release builds, the symbol is redefined to false and a compiler pragma warning is printed.
In particular, the following features become enabled:
Definition at line 44 of file prepro.dox.
| #define ALIB_DEBUG_STRINGS 1 |
Selects extended debug code, mostly within class AString .
If given as true in release builds, the symbol is redefined to false and a compiler pragma warning is printed.
In particular, the symbol enables internal consistency checks as described in chapter 6.4 Debugging Strings of the Programmer's Manual of module ALib Strings . Internally, macro ALIB_STRING_DBG_CHK is used and users of the library are free (recommended) to use the ame for custom consistency checks when manipulating AString buffers directly.
Definition at line 41 of file prepro.dox.
| #define ALIB_DOX |
Defined by Doxygen 
when parsing source code. Not defined with parsers of a C++ compiler. Primarily used to provide a doxygen compatible/readable version of complex declarations and definitions.
Definition at line 35 of file prepro.dox.
| #define ALIB_ENUMS 1 |
Denotes if module ALib Enums is included in the ALib Distribution .
| #define ALIB_EXPRESSIONS 1 |
Denotes if module ALib Expressions is included in the ALib Distribution .
| #define ALIB_EXT_LIB_THREADS_AVAILABLE |
If this symbol is given, then ALib will insert assertions in debug-compilations in the case that module ALib Threads is not included in the ALib Distribution . The assertions will test if a new, unknown thread is executing the code. This test is performed each time a threaded version of the library would acquire a mutex.
If using the default CMake script for ALib , this variable will be set unless either CMake-variable ALIB_CMAKE_SKIP_THREAD_LIB_SEARCH is set to true, or no thread library was found.
Definition at line 13 of file prepro.dox.
| #define ALIB_FEAT_BOOST_REGEX 1 |
Selects code for class RegexMatcher and features within ALib that uses this wrapper class.
If this symbol is not explicitly given to the compiler, it is set to 0, the boost library is not included and class RegexMatcher is not available.
If using the corresponding CMake variable, script build/cmake/ALib.cmake will search and add boost_regex to CMake variable ALIB_EXTERNAL_LIBS.
Please note that this script also performs
set(Boost_USE_STATIC_LIBS ON)
before searching the library.
Definition at line 45 of file prepro.dox.
| #define ALIB_FEAT_BOXING_BIJECTIVE_CHARACTERS 1 |
If 0 (the default), selects code for boxing types char, wchar_t, char16_t and char32_t as a character and disallowing to unbox any other.
If passed as 1, bijective boxing is enabled, what boxes each type as it is.
Definition at line 46 of file prepro.dox.
| #define ALIB_FEAT_BOXING_BIJECTIVE_FLOATS 1 |
If 0(the default), selects code for boxing type float as a double value and disallowing to unbox float.
If passed as 1, bijective boxing is enabled, what boxes type float as it is.
Definition at line 48 of file prepro.dox.
| #define ALIB_FEAT_BOXING_BIJECTIVE_INTEGRALS 1 |
If 0 (the default), selects code for boxing any C++ integral type to integer , respectively uinteger .
If passed as 1, bijective boxing is enabled, what boxes each type "as is".
Definition at line 47 of file prepro.dox.
| #define ALIB_FEAT_SINGLETON_MAPPED 1 |
Affects implementation of class Singleton . If this symbol represents true, then a static hash map is used to find the singleton objects, even if different data segments exist within one software process.
While the overhead imposed by such implementation is quite small, with this symbol being false, the overhead is omitted in scenarios when such effort is not necessary.
The symbol defaults to true on the windows platform, otherwise to false, which may be overwritten by passing the symbol to the compiler.
Definition at line 39 of file prepro.dox.
| #define ALIB_FILES 1 |
Denotes if module ALib Files is included in the ALib Distribution .
| #define ALIB_GCC |
Symbol which is 1 defined when an unknown compiler is used and this compiler is specifying __GNUC__ (what most compilers do). This deduction to "the real gcc" can never be complete, but is the best guess available. A much more complete deduction is provided by boost libraries for example. ALib is tested only on a limited set of platforms/compilers.
Definition at line 11 of file prepro.dox.
| #define ALIB_GDB_PP_FIND_POINTER_TYPES |
This symbol may be passed to the compiler to control the behavior of pretty printers scripts for GDB. If defined, external symbol "ALIB_PP_FIND_POINTER_TYPES" is created with debug builds. This will be detected by pretty printer python script provided with ALib /ALox .
Definition at line 23 of file prepro.dox.
| #define ALIB_GDB_PP_SUPPRESS_CHILDREN |
This symbol may be passed to the compiler to control the behavior of pretty printers scripts for GDB. If defined, external symbol "ALIB_PP_SUPPRESS_CHILDREN" is created with debug builds. This will be detected by pretty printer python script provided with ALib /ALox .
Definition at line 22 of file prepro.dox.
| #define ALIB_GTEST |
Selects unit test code in accordance to the Google Test libraries. Defaults to 0 if not specified.
Definition at line 34 of file prepro.dox.
| #define ALIB_INTGAP_TYPE |
The type of intGap_t . Usually, this symbol is deduced in alib/lang/integers.hpp depending on the compiler and platform
Definition at line 28 of file prepro.dox.
| #define ALIB_MONOMEM 1 |
Denotes if module ALib Monomem is included in the ALib Distribution .
| #define ALIB_PRECOMPILED_HEADER |
Compiler symbol that can be passed to enable inclusions in header file alib/alib_precompile.hpp .
Definition at line 14 of file prepro.dox.
| #define ALIB_RESOURCES_OMIT_DEFAULTS 0 |
If set, code that defines static default resource strings is pruned and thus, all static resource string data is pruned from the library's executable's data segment.
The omission mostly occurs in the implementations of Camp::bootstrap of various ALib Modules , where methods ResourcePool::Bootstrap and ResourcePool::BootstrapBulk are used to define the default resources.
If resources are omitted, the bootstrap process has to be customized to use an external resource provider. Otherwise the library has undefined behavior as resources are missing.
Definition at line 22 of file resources.hpp.
| #define ALIB_SINGLETONS 1 |
Denotes if module ALib Singletons is included in the ALib Distribution .
| #define ALIB_SIZEOF_INTEGER |
Contains the size of std::size_t, std::ptrdiff_t, alib::integer and alib::uinteger, which all should be the same, depending on the compiler and platform (processor type). Usually this symbol is deduced in alib/lang/integers.hpp depending on the compiler and platform. If this deduction fails, this may result in two possible outcomes:
In this case, the right value has to be provided to the compiler. When doing this, symbols
have to be provided as well. This is true for each symbol: If one of them is given explicitly to the compiler, all of the five have to be given. Otherwise an explicit error message will be given during compilation.
Definition at line 26 of file prepro.dox.
| #define ALIB_SIZEOF_INTGAP |
Contains the size of integral types intGap_t and uintGap_t .
Usually, this symbol is deduced in alib/lang/integers.hpp depending on the compiler and platform.
Definition at line 27 of file prepro.dox.
| #define ALIB_SIZEOF_LONGDOUBLE_REPORTED |
Contains the size of long double. This is the value that sizeof(long double) returns. This size might be higher to what a copy operation of a value of the type might write. Usually, this symbol is deduced in alib/lang/integers.hpp depending on the compiler and platform.
Definition at line 29 of file prepro.dox.
| #define ALIB_SIZEOF_LONGDOUBLE_WRITTEN |
Symbol which denotes how many bytes the hardware will write with a value of type long double. This size might be smaller than the amount of memory that an allocation of that type would consume, hence what is reported by sizeof(long double).
Usually, this symbol is deduced in alib/lang/integers.hpp depending on the compiler and platform.
long double. Definition at line 30 of file prepro.dox.
| #define ALIB_STRINGS 1 |
Denotes if module ALib Strings is included in the ALib Distribution .
| #define ALIB_THREADS 1 |
Denotes if module ALib Threads is included in the ALib Distribution .
| #define ALIB_TIME 1 |
Denotes if module ALib Time is included in the ALib Distribution .
| #define ALOX_DBG_LOG 1 |
If defined as true, debug Log Statements are enabled. Hence, users of ALox can conditionally compile special debug logging code that normally belongs to corresponding debug logging statements. This is useful for example, to conditionally compile code that calculates and gathers information to do some more complex log output.
Definition at line 49 of file prepro.dox.
| #define ALOX_DBG_LOG_CI 1 |
If defined, scope information is passed to ALox on invocation of debug Log Statements. Hence, users of ALox can conditionally compile special debug logging code that normally belongs to corresponding debug logging statements based on this symbol. A sample would be the definition of different log line meta information formats, depending on the availability of scope information.
Definition at line 51 of file prepro.dox.
| #define ALOX_REL_LOG 1 |
If defined, release Log Statements are enabled. Hence, users of ALox can conditionally compile special release logging code that belong to corresponding release logging statements. (Note that release logging still can be pruned as explained in 10.3.1 Pruning Release Logging.)
This is useful for example, to conditionally compile code that calculates and gathers information to do some more complex log output.
Definition at line 50 of file prepro.dox.
| #define ALOX_REL_LOG_CI 1 |
Explicitly enables the generation of scope information using the built-in preprocessor macros like "__FILE__" and "__LINE__" for ALox release logging statements, which is disabled by default.
Enabling source info for for release logging is seldom wanted. Release executables should not generate log output that an end user is not able to understand. It can make sense however, if release log information from the field goes back to the software development team. Furthermore, it can be very helpful to enable scope information for release Log Statements if set in the debug version of a compilation unit.
Definition at line 52 of file prepro.dox.