|
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 BitBuffer
Module Boxing
Module Characters
Module Containers
Module Monomem
Module Singletons
Module Strings
Module Threadsd
Camp BaseCamp
Camp Files
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_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_CAMP 1 |
| #define | ALIB_CHARACTERS 1 |
| #define | ALIB_CLI 1 |
| #define | ALIB_CONFIGURATION 1 |
| #define | ALIB_CONTAINERS 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_THREADMODEL 1 |
| #define | ALIB_THREADS 1 |
| #define | ALIB_TIME 1 |
ALib Module BitBuffer Feature Selection | |
| #define | ALIB_DEBUG_ARRAY_COMPRESSION 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 Containers Feature Selection | |
| #define | ALIB_DEBUG_CONTAINERS 1 |
ALib Module Monomem Feature Selection | |
| #define | ALIB_DEBUG_MONOMEM 1 |
| #define | ALIB_DEBUG_ALLOCATIONS 1 |
| #define | ALIB_MONOMEM_POOLALLOCATOR_DEFAULT_ALIGNMENT alignof(uint64_t) |
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 |
ALib Module Threads Feature Selection | |
| #define | ALIB_DEBUG_CRITICAL_SECTIONS 1 |
ALib Module BaseCamp Feature Selection | |
| #define | ALIB_RESOURCES_OMIT_DEFAULTS 0 |
| #define | ALIB_DEBUG_RESOURCES 1 |
| #define | ALIB_PATH_CHARACTERS_WIDE 1 |
ALib Module Files Feature Selection | |
| #define | ALIB_FILES_FORCE_STD_SCANNER 0 |
| #define | ALIB_FILES_SCANNER_IMPL ALIB_FILES_SCANNER_POSIX |
| #define | ALIB_FILES_SCANNER_STDFS 1 |
| #define | ALIB_FILES_SCANNER_POSIX 2 |
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 |
| #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.
| #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.
| #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.
| #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 of 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_CONTAINERS 1 |
Denotes if module ALib Containers 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.
| #define ALIB_DEBUG |
| #define ALIB_DEBUG_ALLOCATIONS 1 |
Maeks all ALib allocators to surround allocations with magic bytes. If given as true in release-builds, the symbol is redefined to false and a compiler pragma warning is printed.
Please consult chapter 11.4 Debugging of the Programmer's Manual of camp ALib Monomem for further information about the debug features that come available with this symbol.
| #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.
| #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.
| #define ALIB_DEBUG_CONTAINERS 1 |
Selects extended debug code in module ALib Containers.
If given as true in release-builds, the symbol is redefined to false and a compiler pragma warning is printed.
Please consult chapter 11.4 Debugging of the Programmer's Manual of module ALib Containers for further information about the debug features that come available with this symbol.
| #define ALIB_DEBUG_CRITICAL_SECTIONS 1 |
This symbol - while associated to module ALib Threads - activates type lang::DbgCriticalSections, which is available independent of the inclusion of this module. However, the symbol itself will always be disabled (set to 0) if module ALib Threads is not included in the ALib Distribution. This design allows using the corresponding macros anywhere in the code, without further checks. In the absence of ALib Threads, all macros will be just empty. The same is true for type
DbgCriticalSections, which will be completely empty and optimized out.
| #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.
Please consult chapter 11.4 Debugging of the Programmer's Manual of camp ALib Monomem for further information about the debug features that come available with this symbol.
| #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:
| #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.
| #define ALIB_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.
| #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.
| #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.
| #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.
| #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".
| #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.
| #define ALIB_FILES 1 |
Denotes if module ALib Files is included in the ALib Distribution.
| #define ALIB_FILES_FORCE_STD_SCANNER 0 |
If given, platform-specific code for scanning files is ignored and instead function ScanFiles uses an implementation based on C++ library std::filesystem. This flag was is used by the developers of ALib to test the standard implementation and should not be set otherwise, because platform-specific implementations are more feature reach and better performing.
Definition at line 19 of file fscanner.hpp.
| #define ALIB_FILES_SCANNER_IMPL ALIB_FILES_SCANNER_POSIX |
This symbol is evaluated internally and available after inclusion of alib/files/fscanner.hpp. It allows determining the implementation of the file scanner used. As of this library version, the following values are possible:
Must not be set from outside. Use ALIB_FILES_FORCE_STD_SCANNER.
Definition at line 32 of file fscanner.hpp.
| #define ALIB_FILES_SCANNER_POSIX 2 |
A possible value of ALIB_FILES_SCANNER_IMPL, evaluating to 2, and denoting the implementation using the Posix library calls.
Must not be set from outside.
Definition at line 27 of file fscanner.hpp.
| #define ALIB_FILES_SCANNER_STDFS 1 |
A possible value of ALIB_FILES_SCANNER_IMPL, evaluating to 1, and denoting the implementation using C++ library std::filesystem.
Must not be set from outside.
Definition at line 26 of file fscanner.hpp.
| #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.
| #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.
| #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.
| #define ALIB_GTEST |
| #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
| #define ALIB_MONOMEM 1 |
Denotes if module ALib Monomem is included in the ALib Distribution.
| #define ALIB_MONOMEM_POOLALLOCATOR_DEFAULT_ALIGNMENT alignof(uint64_t) |
This symbol defaults to "alignof(uint64_t)" and is used as the default value of template parameter TAlignment of class TPoolAllocator. The importance of this default value arises from the fact that the alias type definition alib::PoolAllocator uses this default-alignment and this alias is in turn used across ALib. In case this value needs to be changed, please note that the using code linked against a compiled library needs to have this symbol set accordingly. Otherwise, undefined behavior may occur.
Definition at line 23 of file boxing/fwds.hpp.
| #define ALIB_PATH_CHARACTERS_WIDE 1 |
This symbol is set to 1 if the character type defined by the C++ standard library with type std::filesystem::path::value_type is wchar_t. Otherwise it is set to 0.
The symbol is set in alib/lang/system/path.hpp but can only be "guessed". The guess is that only if symbol _MSC_VER is set, wide characters are used. The header fail raises a static assertion error if the macro is wrongly guessed or externally set.
Should the guess be wrong, the right value has to be passed with compilation of the library.
| #define ALIB_PRECOMPILED_HEADER |
Compiler symbol that can be passed to enable inclusions in header file alib/alib_precompile.hpp.
| #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 16 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.
| #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.
| #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.
| #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. | #define ALIB_STRINGS 1 |
Denotes if module ALib Strings is included in the ALib Distribution.
| #define ALIB_THREADMODEL 1 |
Denotes if module ALib ThreadModel 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.
| #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.
| #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.
| #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.