ALib C++ Library
Library Version: 2402 R1
Documentation generated by doxygen
Loading...
Searching...
No Matches
Change Log

Version 2402, Revision 1, released March 4th, 2024

  • Fixed the version number, which still was set to 2312R0, now it is 2402R1
  • Several minor fixes in the documentation.

Version 2402, Revision 0, released February 29th, 2024

Yes, we used the gained hours of this extra leap year day to create a fresh release of ALib !

This version was successfully tested under the following platform and toolchain combinations:
  • GNU/Linux Arch 6.7.6, GNU C++ 13.2.1 / Clang++ 16.0.6, C++ 17/20, 32-Bit / 64-Bit
    (This is the main development platform.)
  • Windows 10/11, MSC 17.8.3 (Visual Studio 2022), C++ 17/20, 32-Bit / 64-Bit
  • Windows 10/11, MinGW, C++ 17/20, 64-Bit
  • MacOS Sonoma 14.3.1, Apple M2 / ARM64, Apple Clang Version 15.0.0, C++ 17/20, 64-Bit
  • Raspberry 3, ARM, 64-bit OS, GCC 10.2.1, C++ 17/20, 64-Bit
  • Raspberry 4, ARM, 64-bit OS, GNU C++ 12.2.0, C++ 17/20
C++ Language Standard Support
Removed support for C++ 11 and 14. Compilation will test the language standard and explicitly fail with an error message with these standards.
On the same token, added preliminary support for C++ 23. (The library compiles and unit tests run with C++ 23 compilation under GNU/Linux clang/gcc.)
Preprocessor Symbols:
  • Renamed symbol ALIB_CPPVER to ALIB_CPP_STANDARD.
  • Symbol ALIB_CPP_STANDARD is now allowed to be given from outside. This may be used with compilers unknown to ALib, where the auto-detection fails.
  • Symbol ALIB_CPP_STANDARD will now contain 23, if this language standard was used in the build process.
  • Removed symbols ALIB_CPP11, ALIB_CPP14, ALIB_CPP17 and ALIB_CPP20 in preference to exclusively using ALIB_CPP_STANDARD.
  • Due to dropping C++ 11/14 support, removed macros
    • ALIB_WARNINGS_IGNORE_IF_CONSTEXPR,
    • ALIB_CPP14_CONSTEXPR,
    • ALIB_CPP17_CONSTEXPR,
    • ALIB_CPP14_REL_CONSTEXPR,
    • ALIB_CPP17_REL_CONSTEXPR and
    • ALIB_NODISCARD
  • Due to preliminary support for C++ 23 support, added macros
Library Organization:
Several changes have been made in the organization and structure of the library. Existing projects need to be adopted. This concerns probably each compilation unit, and we are sorry for this. However, most of the work needed is change inclusion paths of some files and changing the namespace name of ALib types.
The following gives a rough overview of what have been done:
  • Former namespace aworx has been renamed to alib.
    Its inner namespace aworx::lib has been removed completely, so that all namespaces of the ALib Modules are now directly located in outer namespace alib.
  • The concept of "file-sets" has been dropped. Instead, the few files that did not find a home with one certain ALib Module have been moved to source folder src/alib/lang and just have to be included with an ALib Distribution , as documented here.
  • New namespace alib::lang holds all library types which are very close to the C++ language and which are not related to specific ALib Modules .
  • The terminology of ALib Micro Module, ALib Full Module has been dropped:
    Everything is an ALib Module now. Those that need configuration data and or resources (the ones that had been called "full modules"), are now called ALib Camps .
    Instead of former class aworx::lib::Module, they now inherit class alib::lang::Camp. For further information, read here.

  • Special module ALibDistribution was renamed to ALib BaseCamp . Then the following former modules have all been integrated into this single module:

    • aworx::lib::resources
    • aworx::lib::text
    • aworx::lib::results
    • aworx::lib::system

    This dropped the number of modules from 17 to 14. With one new added (see below), ALib now presents 15 modules.

  • All bootstrapping and corresponding shutdown is now executed with overloaded namespace functions alib::Bootstrap and alib::Shutdown. This is well documented in completely overhauled chapter 4. Bootstrapping And Shutting Down ALib of the module-agnostic Programmer's Manual of the library.
Core library types:
  • Fixed a bug im method CLZ0(TIntegral) to return sizeof(TIntegral) * 8 in case the given value is zero, just as documented. It returned 0 before.
  • Added functions CTZ(TIntegral) and CTZ0(TIntegral) using intrinsics.
  • Added functions alib::lang;UpperMask<TWidth;TIntegral>();UpperMask<TWidth;TIntegral> "lang;UpperMask<TWidth;TIntegral>();UpperMask<TWidth;TIntegral>" and UpperMask<TIntegral>(ShiftOpRHS) .
  • Removed function BitCounterWidth<TIntegral>() and replaced it with Log2OfSize() , which returns the former functions result -1.
  • Changed functions LowerMask<TIntegral>(ShiftOpRHS) and alib::lang;LowerBits<TIntegral>(ShiftOpRHS;TIntegral);LowerBits<TIntegral> "lang;LowerBits<TIntegral>(ShiftOpRHS;TIntegral);LowerBits<TIntegral>" to assert a width overflow. Previously this was tolerated and corrected. This approach was considered inefficient in most cases
  • Added preprocessor macro bitsof and namespace function bitsofval .
  • Added class TBitSet to new header alib/lang/bitset.hpp , which is a more sophisticated replica of std::bitset.
  • Added type definition EnumBitSet which allows to use new type TBitSet conveniently with enumeration types.
CommonEnums:
Module Enums:
Module Time:
Module Strings:
Module Monomem:
  • Removed the first three entries (11, 23 and 47) of the list of prime numbers used to determine the (next higher) bucket size of class HashTable to avoid unnecessary rehash on initial growth in the common use cases. Consequently, the minimum bucket size now is 97 instead of 11.
    This should be a more realistic value. And: global objects that are using the GlobalAllocator can not be bootstrapped to a higher capacity (due to C++ bootstrap mess) without adding explicit bootstrap code. Those are now preset with a higher size.
  • Refactored class StringTree to not request to initialize a value of template type T associated with it's root node during construction. Even more, it is not possible anymore, instead new methods ConstructRootValue and DeleteRootValue have to be used to 'optionally' attach custom data to the root node. This approach has several advantages. Further information on this topic is found here.
  • Renamed StringTree::NodePtr to StringTree::Cursor . (Ok, we did this once already the other way round. Well...)
  • Added types StringTree::ConstCursor and StringTree::ConstRecursiveIterator to allow to the read-only traverse of objects type const StringTree.
  • Added methods {monomem,StringTree::NodeTable} to allow access to the internal node storage. Of-course, this object has to be used with caution.
  • Method TCursor::AssemblePath was optimized in respect to performance and with that, now returns an absolute path. With other words, the path separation character is prepended.
    An alternative method, which again returns a relative path from the root node, was added as an overloaded version. In addition, this overload allows to create relative paths not only from the root node, but from any other parent node.
  • Removed unnecessary intermediate dynamic allocations that occurred when using StringTree with template node maintainer StringTreeNamesDynamic . On the same token, added debug statistic variables DbgStatsStringTreeNames and DbgStatsStringTreeNameOverflows to support choosing a reasonable internal buffer size, which is application dependent.
Module BASECAMP:
Module Files:
This is a new module which provides powerful directory and file scanning capabilities. Still an initial version but equipped with a tutorial-style Programmer's Manual.
Module ALox:
This release finally integrated all artifacts of documentation and things that had remained on former joint project ALox for C++,C# and Java into this site. The complete ALib Module ALox - Programmer's Manual (70 pages) and the ALox - Tutorial (another 27 pages) have been reviewed and overhauled.

Version 2312, Revision 0, released December 13th, 2023

Note
Yes, it hast been four years since the lasst release. What esd called a "global pandemic" distracted me (the main programmer of this library) in many respects from working on open source projects. Probably in a very different sense than some of you would expect.
Please take my excuse!
This version was successfully tested under the following platform and toolchain combinations:
  • GNU/Linux Arch 6.6.6, GNU C++ 13.2.1 / Clang++ 16.0.6, C++ 11 - 20, 32-Bit / 64-Bit
    (This is the main development platform.)
  • Windows 10/11, MSC 17.8.3 (Visual Studio 2022), , C++ 11 - 20, 32-Bit / 64-Bit
  • Windows 10/11, MinGW 11.0, C++ 11 - 17, 64-Bit ( C++ 20 does not compile! with current MinGW!)
  • MacOS 13, Intel i9, AppleClang 14.0.3, C++ 11 - 20 C++, 64-Bit
  • MacOS 13, Apple M1/ARM64, C++ 11-20, 64-Bit
  • Raspberry 3, ARM, 64-bit OS, GCC 10.2.1, C++ 11 - 20, 64-Bit
  • Raspberry 4, ARM, 32-bit OS, GNU C++ 12.2.0, C++11-20
  • Raspberry 4, ARM, 64-bit OS, GNU C++ 12.2.0, C++11-20
CMake Build System
  • Fixed the meanwhile lost ability to generate a static ALib library. Obviously a change in the CMake default behaviour caused to build and link a shared library with the use of provided method ALibAddStaticLibrary.
  • Added setting set(Boost_USE_STATIC_LIBS ON) in build/cmake/ALib.cmake . This avoids rebuilding a project on systems that update Boost libraries.
  • Renamed CMake variables ALIB_COMPILE_FLAGS to ALIB_COMPILER_OPTIONS and ALIB_LINKER_FLAGS to ALIB_LINKER_OPTIONS.
Preprocessor Symbols:
General Changes:
  • Adopted code to compile smoothly with current clang version clang compiler 14.0.6 and GNU Compiler Collection 12.2.0 . (As always a minimum set of notorious warnings are disabled, only)
  • Removed former filesets debug and integers in favour to reduce compilation/setup complexity. Corresponding files are now included in each ALib Distribution with header files:
    • lib/integers.hpp and
    • lib/tools.hpp The latter was available before, but now includes the contents of removed files assert.hpp and typedemangler.hpp
  • Added library header lib/bits.hpp, which adds the following functions to namespace aworx::lib:
    • aworx::lib::BitCount
    • aworx::lib::CLZ
    • aworx::lib::CLZ0
    • aworx::lib::MSB
    • aworx::lib::MSB0
    • aworx::lib::BitCounterWidth
    • aworx::lib::LowerMask
  • Minor fixes of fileset dependency evaluation in file "lib/modules.hpp".
  • Removed use of deprecated type "std::iterator". (Replaced by use of "std::iterator_traits".)
  • Renamed identifiers containing the misspelled word "iteratable" to "iterable". I.e. template typeT_EnumIsIterable , macro ALIB_ENUMS_MAKE_ITERABLE and also header file alib/enums/iterable.hpp
  • Slightly corrected bootstrapping order of micro modules to be
    1. ALib Time ,
    2. ALib Boxing and
    3. ALib Threads .
ALib Debug Support:
  • Added parameter topic to overloaded methods aworx::lib::DbgSimpleALibMsg. Changed all invocations within the library to provide a topic.
Fileset "CommonEnums":
  • Extracted enum alias definitions in namespace aworx into new header file "lib/fs_commonenums/commonenumdefs_aliased.hpp".
  • Added common enum aworx::lib::ValueReference.
Fileset "Lists":
  • Moved classes of this fileset to new sub-namespace aworx::lib::detail.
  • Renamed and simplified helper classes of this fileset.
Fileset "Plugins":
  • Moved class detail::PluginContainer to new sub-namespace aworx::lib::detail.
Fileset "Modules":
  • Added field ALibDistribution::LocaleFound that allows to get confirmation that the locale that was automatically set as described in ALibDistribution::bootstrap. This is now used by the unit tests to avoid errors due to failure of unicode conversion just for the sake of missing environment variables in dubious development environments.
Module Resources:
Module Enums:
Module Boxing:
  • Defined static vtables for ALib Boxing for the following types:
    • Common enumeration types provided with ALib .
    • std::type_info
    • results::Exception
    • results::Report::Types}
    • Token
    • ALib string types when wrapped in std::reference_wrapper.
    • Added convenience method Box::UnboxMutable .
Module Strings:
  • Fixed comparison operators to be compatible with ambiguities that occur with C++ 20 language standard. Likewise, with C++ 20 the spaceship operator '<=>' is now used instead.
  • Added method AString::Reverse and underlying implementation CharArray::Reverse .
  • Added checks for field ostream with output methods of class compatibility::std::StringWriter .
  • Fixed a bug in floating point number conversion, which in rare cases caused an ALib exception in debug builds and a falsely rounded output string in release builds.
  • Fixed move constructor of class AString not also reset the capacity, but also the length of the moved string to 0.
  • Method String::WStringLength now, in case of failure, returns the strings' unconverted length instead of -1.
Module Time:
Module Threads:
Module Monomem:
  • Fixed method List::ElementAt (and added missing unit test).
  • Added constructor parameter chunkGrowthInPercent to alib::monomem;MonoAllocator::MonoAllocator(size_t; unsigned int);MonoAllocator "monomem;MonoAllocator::MonoAllocator(size_t; unsigned int);MonoAllocator" which allows exponential growth of allocated chunk sizes.
  • Fixed a bug in method alib::monomem::HashTable::Erase(ConstIterator " ConstIterator) " which lead to a double invocation of a destructor of the first element removed. Improved unit tests to detect problems of this kind in the future.
  • Added container type FixedCapacityVector and type definition FixedSizePriorityQueue.
  • Removed method HashTable::Rehash. See reference documentation for the rationale.
  • Added parameter reference to methods HashTable::Reserve , HashTable::ReserveRecyclables and StringTree::ReserveRecyclables .
  • Constructor of StringTree now reserves a minimum number of internal buckets to prevent the creation of a non-recyclable bucket list on future growth.
  • Added missing template parameter TLocalCapacity to alias name aworx::StringTreeNamesDynamic.
  • Fixed bug in overloaded variant of HashTable::EmplaceOrAssign which could generate a compiler error due to not properly forwarding the hash functor.
Module "Results":
  • Adopted method results::ReportWriterStdIO::Report to interpret the first parameter of a method as a "topic". The rules to detect such topic follow the rules of auto-detecting domain names in higher level module ALox , which replaces the report writer for internal messages.
Module Text:
  • The backslash of newline characters in format strings do not need to be escaped itself anymore. For example, format string 
      "Value 1: {}\\nValue 2: {}"
    may now be written 
      "Value 1: {}\nValue 2: {}"
    All occurrences in resource strings and log output have been changed to use the single-slash version.
  • Replaced abstract virtual method FormatterStdImpl::replaceEscapeSequences with writeStringPortion (performance optimization).
  • FormatterStdImpl now performs custom formatting whenever a custom boxing function FFormat is defined for a given boxed formatting argument. In previous versions, this was done only if a custom format string was provided with the corresponding placeholder of the format string.
    Consequently, custom implementations of FFormat now have to cope with empty format strings, for example by using a (resourced) default string.
Module Config:
Module System:
  • FFormat_DateTime now uses a default format string in the case no format was given. The format string is resourced with key "DFMT".
  • Extracted system error definitions from system/system.hpp to system/systemerrors.hpp (to reduce inclusion dependencies)
  • Added class CalendarDate .
Module ALox:
  • Fixed special shortcut header alib/alox.hpp to include distribution.hpp to allow single inclusion of "alib/alox.hpp" to automatically bootstrap and use ALox functionality as instructed in the tutorial.
  • Added method Lox::IsActive to detect the number of loggers that are active for a combination of domain and verbosity.
    Likewise added macros Lox_IsActive and Lox_IsActive.
  • Class TextFileLogger now tests file for possible access during construction. Errors may be evaluated with new field TextFileLogger::LastSystemError , which replaced former boolean field hasIoError that only was set after a (first) log operation.
Module Expressions:
  • Moved mechanics to implement automated named expressions into new dedicated abstract interface class ExpressionRepository .
    A standard implementation for it is provided with StandardRepository . Implementations are to be set to new field Compiler::Repository . Consequently, all corresponding former entities in class Compiler (namely Config, DefaultCategories, VariablesLoaded, StoreLoadedExpressions and getExpressionString) have been removed.
  • Verbal aliases of binary operators are no longer conflicting with identifier/function names. For example, a function named "equals" may now be defined while the same string is used for a verbal operator alias.
  • Simplified syntax of format strings of type ExpressionFormatter .
New Module CLI:
This module is not completely new, but with this version it comes in its first "release" state. Along with it, a brief Programmer's Manual ALib CLI is provided. This manual includes a step-by-steb sample, which can well be used as a jump-start template for your own project.
New module "BitBuffer":
This ALib release introduces a new module ALib BitBuffer which provides mechanism to serialize application data into streams of bits. The following classes are included:

A brief manual explains the use of this new module.

Version 1912, Revision 0, released December 16th, 2019

Main Achievements Of This Release:
  1. After the massive restructuring of the library with previous version 1903, some more refactoring had to be done to adopt the module concept everywhere and fine tune it.
    Therefore, with this release, various incompatibilities are again expected. We (still) have hopes that ALib becomes more stable over time.
  2. The concept of "ALib Enum Meta Data"
    • has been renamed to ALib Enum Records and was rewritten from scratch. It is now much more simple in use and yet more powerful.
    • was formerly spread between modules ALib Enums and ALib Resources, and is now 100% located in ALib Enums .
    • Its documentation had been spread over reference documentation of various types and is now concentrated in chapter 4. Enum Records of the now available Programmer's Manual of that module.
  3. Module ALib Resources has been revised. Resources are now more strictly defined to be static data. While the core principles remained intact, almost every entity in the module has been refactored to be simpler and faster.
  4. Bootstrapping of ALib and custom modules was slightly revised.
  5. The most important new feature: Module Memory (which was almost empty before) has been renamed to ALib Monomem and filled. Its new functionality has been documented with a new Programmer's Manual and it is used with almost every other module.
    This reduced the number of memory allocations made during the unit test by around 80% and the time to execute all test by around 25% in debug builds and more than 15% in release!
    Depending on a user's application's nature (in respect to memory consumption) the use of this module has a huge potential for a performance boost for many applications.
  6. The former separation between "compiler symbols", aka definitions passed to the compiler and "code selection symbols" has been dropped. While it was motivated by "good intentions", we realized that it complicates things too much and the industry is used to not have this separation.
    When using CMake to build the library, this should not have much impact on existing user's code base.
  7. Finally, we tried to reduce header file dependencies, which results in faster compilation but unfortunately also further incompatibilities when switching to this version.

As a summary, existing user code will need various changes to adopt - and we again excuse for that. We hope that during the process of adopting your code, you will see the benefits of all changes.

General Changes:
  • Dropped the concept of "compiler symbols". If not explicitly documented otherwise, code selection symbols (that formerly where derived from compiler symbols passed with option -D ) are now directly possible to the compiler with the same option name instead of using postfixes _ON or _OFF.
  • Cleaned header file inclusion across ALib to improve compilation speed.
    Moving to this version will likely impose the need to include some specific headers in a using software, which previously had been included internally.
  • Removed all redundant semicolons from the source (I.e. to allow compiler warning "-Wextra-semi" set with GCC or Clang).
  • Removed all redundant keywords inline from the source.
  • Corrected many typos in manuals.
  • Updated documentation to be compatible to new doxygen release 1.8.16.
  • Added header inclusion diagrams to the documentation. Also added documentation pages for each ALib source folder and header file and a link from almost each C++ entity to the corresponding header file of its declaration.
  • All variadic template types that had been named Args have been renamed to TArgs for consistency with ALib naming conventions.
  • Renamed all code selection symbol for modules from ALIB_MODULE_XYZ to ALIB_XYZ, for example ALIB_MODULE_THREADS to ALIB_THREADS.
    On the same token added macros ALIB_IF_XYZ and ALIB_IFN_XYZ for each module. (For example ALIB_IF_THREADS and ALIB_IFN_THREADS.) Those are useful to reduce #if/#endif clutter in the code.
  • Renamed symbol ALIB_DOCUMENTATION_PARSER to ALIB_DOX and changed it from being defined to 0 to being undefined with compiler runs.
CMake Build System / Filesets / Sources:
  • Removed former filesets PREDEF_PF and PREDEF_TMP, and defined the associated mostly preprocessor-related header files to be included in any ALib Distribution .
  • Moved sources of filesets to sub-directories named src/lib/fs_XYZ.
  • Added dependency to filesets "INTEGERS" and "DEBUG" for micro module ALib Singletons .
  • Removed fileset "TYPEMAP".
  • Added new fileset "LISTS" containing generic node types and iterators for internal use with single and doubly-linked lists.
  • Prior to the invocation of ALib.cmake, entry "ALIB_SUPPRESS_COMPILER_WARNINGS" can now be added to list variable ALIB_COMPILER_WARNINGS. If so, this entry is removed and the script will not add any warning settings to the symbol.
  • Fixed bug in CMake script that prevented cached variable ALIB_PRECOMPILED_HEADER_DISABLED to disable precompiled header alib/alib_precompile.hpp . Renamed the variable to be ALIB_PRECOMPILED_HEADER, defaulting it to Off.
  • The CMake script now searches the target system's thread library independent from the inclusion of module ALib Threads . Instead, new CMake variable ALIB_CMAKE_SKIP_THREAD_LIB_SEARCH controls the search and may be used to disable this.
  • Renamed CMake variable ALIB_MODULE_SOURCE_COPY_DIR to ALIB_SOURCE_COPY_TARGET_DIR.
  • Renamed CMake variable list ALIB_MODULES to ALIB_DISTRIBUTION.
Preprocessor Symbols:
  • C++ version macros:
    • Added macro ALIB_CPPVER which contains one of C++ version numbers 11 to 20.
    • Added macro ALIB_CPP11 which is set if exactly C++ 11 is used.
    • Added macro ALIB_CPP20 which is set if exactly C++ 20 is used (never set, yet).
    • Changed meaning of macro ALIB_CPP14, which now is unset if a C++ version higher than 14 is used.
    • Removed macro ALIB_REL_CONSTEXPR. It was replaced in a former release already by macros ALIB_CPP14_REL_CONSTEXPR and ALIB_CPP17_REL_CONSTEXPR
Fileset "Modules":
Revised bootstrapping which is implemented mainly with class Module. Various changes have been made, for example:
  • The point of creation of a resource pool and configuration object, and their distribution during the course of bootstrapping was slightly revised.
  • A new contract rule now disallows multi-threaded access during bootstrap, which relieves bootstrap code from using locks (mutexes).
  • Module termination is now a phased process too: The first phase, Module::ShutdownPhases::Announce, was added to give each module the chance to perform tasks while the library is still 100% intact and initialized.
  • Methods Init and TerminationCleanUp have been renamed to Module::Bootstrap and Module::Shutdown. Likewise, all interfaces throughout ALib that are deemed to be used exclusively during bootstrap, have also been renamed and prefixed by the term Bootstrap. (For example ResourcePool::BootstrapBulk .)
Fileset "Common Enums":
  • Added common enumeration Side.
  • Added common enumeration Caching.
  • Most types now use underlying type bool.
Fileset "Plugins":
  • Class PluginContainer does not inherit from ThreadLock any more.
Fileset "Lists" (new):
This new fileset starts with providing types ForwardNode, ForwardList, ForwardListIterator, BidiNode, BidiList and BidiListIterator, which are considered "internal types" when implementing single- or doubly-linked lists.
Module Characters:
Module Boxing:
  • It is now allowed to invoke Box::TypeID on uninitialized boxes. For those, typeid(void) is returned.
  • The constraint to box a type by default "as value" was extended to types being trivially destructible.
  • Class Boxes :
    • Now optionally accepts a MonoAllocator with construction
    • The constructor taking variadic arguments was removed. This intentionally disables implicit construction of an instance of the class with the invocation of methods that expect a parameter of type const Boxes&.
    • Methods Boxes::Add now return a reference to the invoked object.
  • Renamed namespace function EnumValue to UnderlyingIntegral .
  • Renamed method Enum::Value to Enum::Integral .
  • Fixed a minor memory leak with custom box-functions that were not deleted on program termination. (This was only an issue for mem checking tools like Valgrind .)
  • Added compilation symbol ALIB_DEBUG_BOXING. Without this being given, debug features of the module are no longer available in debug-builds.
  • Renamed macro ALIB_BOXING_VTABLE_REGISTER to ALIB_BOXING_BOOTSTRAP_VTABLE_DBG_REGISTER.
  • Removed debug tables DBG_KNOWN_VTABLES and DBG_KNOWN_VTABLES. Instead, method DbgBoxing::GetKnownVTables was added and along with that, method DbgBoxing::GetKnownFunctionTypes is now available also in ALib Distributions that only contain module Boxing.
  • Changed management of custom box functions to using one global hash table instead of many linked lists. This might slightly decrease performance with small applications (not noticeable) but scales in an average of O(1) when many different custom function types are declared.
Module Strings:
  • Attention: The default constructor of class String now is default-implemented and leaves an instance in uninitialized state. (Formerly the instance was in nulled state with default construction.)
    The rational for this is to avoid redundant initializations and with that, type String is now a POD type. Consequently it is now a user's obligation to assure strings used are initialized.
    (Note: within all of ALib , only a handful of explicit initializations had to be added. By using analyzer tool Valgrind , those could be detected with little effort.)
  • Fixed a bug in method TString::indexOfString , which could cause illegal memory access and other undefined behavior in seldom cases.
  • Removed class strings::util::StringTable. Its only use was in module boxing to implement debug output and consequently was moved to DbgStringTable .
  • Removed the simple templated inline namespace functions strings::util::FindStringInTupleVector and strings::util::FindStringStartInTupleVector. They got replaced by anonymous (local) definitions.
  • Removed constructor and methods Format and FormatArgs from class AString . Those methods and constructors had formerly allowed to use an AString as an interface to string format operations which used the default formatter. The rational to remove this functionality is to reduce module dependencies, construction parameter ambiguities and to have a more explicit API.
  • Moved class StringTree from module ALib Strings to module ALib Memory and completely overhauled its implementation, aiming to optimize memory consumption, performance, flexibility and ease of use. This overhaul implies a complete change in its interface, public inner types, etc, which are not listed here one by one.
  • Added inline namespace method AllocateCopy and DeleteString .
  • Moved methods ConsumeEnum, ConsumeEnumBitwise and ConsumeEnumOrBool from class Substring to corresponding functions in namespace aworx::lib::enums.
Module Threads:
  • This module can now be excluded from any permutation of modules of an ALib Distribution , which turns such distribution into a "single threaded" version of ALib . This is considered a new feature (as formerly, module ALox had a strict dependency). More on that topic is found in the new manual section 2.4.4 Single Threaded Library Compilation.
  • The module is now independent of module ALib Time (the prior minimal use pieces, exclusively in debug-builds, were re-implemented)
  • Uses monotonic allocation for thread management.
  • Already in previous versions, macros ALIB_LOCK and ALIB_LOCK_WITH remained defined if module ALib Threads was not included in an ALib Distribution . Now in addition these macros will invoke test function DbgCheckSingleThreaded in debug-compilations, that asserts if a second thread visits library code that needs protection.
  • Re-implemented bigger parts of ThreadLock with slight changes in its interface.
Module Monomem (formerly Memory):
Module Resources:
  • Overhauled resource management:
    • Programmer's Manual was rewritten.
    • Renamed type Resources to ResourcePool and made it pure abstract interface type.
    • Renamed methods of ResourcePool to more precise and better readable names.
    • Removed ability to store non-static resource strings.
    • Added new type LocalResourcePool as the default interface implementation
    • Added new type ConfigResourcePool an optional interface implementation.
    • Adopted changes in type Module.
    • Adopted changes in library's Programmer's manual, chapter 4. Bootstrapping And Shutting Down ALib.
  • Removed all previously included functionality of former concept "ALib Enum Meta Data", which was completely rewritten to new concept ALib Enum Records and located in module ALib Enums .
  • Uses monotonic allocation for resource management.
  • Removed class ResourceString.
  • Fixed a bug that prevented to add resources for common enum types, if module ALib Configuration was not included in the ALib Distribution .
Module Results:
  • Adopted concept ALib Enum Records.
  • Changed class results::Message to derive from class Boxes , instead of owning a field Args of that type.
  • With the change of class Boxes as documented above, a message may optionally now use monotonic allocation.
  • Changed class results::Exception to derive from new struct SelfContained (and removed corresponding proprietary code that previously stored the type's fields inside the allocator). Together with the above, this fulfills a former promise to have a typical ALib exception perform only one single memory allocation.
Module Text: (Formerly Stringformat)
  • Renamed module Stringformat to ALib Text
  • Method Formatter::Acquire now returns an internal container of type Boxes, which optionally can be used to collect formatting arguments. If it is used, new method Formatter::FormatArgs(AString&) allows using this list.
  • Overloaded methods methodFormatter::FormatArgs does not acquire the formatter anymore. Acquirement and a corresponding release of the formatter object, has to be performed explicitly by the calling code. In case of formatting exceptions, those have to be caught to release the formatter and eventually be rethrown or otherwise processed.
  • Fixed method FormatterStdImpl::writeStdArgument to write raw integral box contents with binary, octal and hexadecimal output formats. (This was broken since the most recent release only)
    On the same token, the method was changed to use the full (platform-dependent) output width for pointer and array types, in the case no output width specifier had been given. E.g. if a pointer is given with hexadecimal output, 16 digits are printed on a 64-bit platform.
  • Extended conversion option {!Quote} of formatter FormatterPythonStyle to optionally specify the quote character(s) that an argument should be surrounded by.
  • Removed creation of class Boxes with method alib::lang::format::Formatter::Format(AString " const TArgs&...)" . (This was accidentally inserted and totally superfluous.)
Module Configuration:
  • Adopted concept ALib Enum Records.
  • Class Variable now inherits new struct SelfContained and thus is very memory efficient. This caused various interface changes in the area of getting and setting variable attributes and values.
  • Constructors of class Variable as well as method Variable::Declare now accepts a single Box instead of variadic template arguments to define replacement information. In the case that more than one replacement object should be passed, those have to be encapsulated in an instance of class Boxes .
  • Class InMemoryPlugin was rewritten and changes adopted by derived type IniFile . It now uses monotonic allocation and shows better performance. Various changes in the rather internal interface are not listed here.
  • Added method IniFile::AddResourcedSectionComments , which replaces a former less flexible approach to add resourced (externalized) comments to sections, when they get created programatically.
  • Added field IniFile::LineWidth , which may be used to adjust the preferred line width when formatting comments of sections and entries.
Module ALox:
  • This module is now independent from the availability of module ALib Threads . If not available, the library is deemed to be a single-threaded version, which was formerly not possible when module ALox was included in an ALib Distribution .
  • Reorganized code structure to reduce header dependencies. Header file alib/alox.hpp is now a shortcut to alib/alox/alox.hpp , which now only includes things needed to perform basic debug- and release-log operations.
    Class ALox is not included by default anymore. If needed (e.g. for initialization of the module or for registration of instances of Lox), header file alib/alox/aloxmodule.hpp has to be explicitly included.
    To allow the reduction, class Lox was implemented using the Pimpl Idiom .
  • Header file alib/alox.hpp is now included in all ALib Distributions , even those that do not include module ALox . If ALox is not available, this header will define the logging macros empty. This simplifies the insertion of logging code into sources that are only optionally used in combination with ALox.
  • Text formatters now duly catch exceptions raised by their internal Formatter instances, e.g. when malformed placeholder syntax occurs in logging code. In this case the originally intended log message is extended with information on the exception that was raised.
  • Uses monotonic allocation in various places and this way a further reduced use dynamic memory allocations was achieved.
  • Moved field ALox::InternalDomains to Lox::InternalDomains .
Module Expressions:
  • Dropped the support of using boost::spirit for parsing. To maintain the option to alternatively use this library caused reasonable problems and is considered not important due to the huge constraints this library is subject to.
  • Various internal changes to replace dynamic memory allocations with monotonic allocation, by adding MonoAllocator to type Compiler and by using new container types of module ALib Monomem wherever possible.
  • Changed method name Scope::Clear to Scope::Reset .
  • Renamed field Scope::nestedExpressionStack to Scope::NestedExpressions
  • Moved the compile-time scope object from class detail::Program to Expression::ctScope .
  • Simplified class Calculus , which now treats unary and binary operators merely the same. As a consequence, almost all fields and methods of the class that formerly had the words "unary" or "binary" in their name are replaced by generically named version that now handle both operator types.
  • Fixed documentation chapter 11.6 Shared Resources And Concurrent Use. The restrictions on parallel method invocation (multi-threading) were defined too weak. Now, with the optimizations in respect to memory consumption, the restrictions became even stronger. Nevertheless, this should not impose a major difficulty in implementing multi-threaded expression usage.
  • On the same token, removed all internal thread-locking mechanics. Consequently, those are now an obligation of the using code to be performed. This is a much easier and clearer design.
  • Removed class ScopeString and replaced with new class TMAString .
  • Renamed enum flag AllowBitwiseBooleanOperations to AllowBitwiseBooleanOperators .
  • Resourced (externalized) names of built-in types Types .
Compatibility Headers:
  • Moved overloads of operator<< given with alib/compatibility/std_strings_iostream.hpp from namespace aworx to the global namespace. Documentation still resides in "fake namespace" aworx::lib::strings::compatibility::std.
  • Various minor changes not listed here.

Version 1903, Revision 0, released March 14th, 2019

Attention
Once more, this library version is not tested (probably does not compile!) under Mac OS. While we promise to fix that rather quickly now, we would also be thankful if volunteers from the community would provide such support.

This is a complete overhaul of the library. With the separation of this C++ implementation from the sibling libraries implemented in programming languages Java and C# (see chang log entry Version 1805 below), this C++ version was "set free" from many compromises that were formerly made to keep the language versions compatible.

As a result, ALib for C++ is now 100% modern C++! (To the extent that the authors of this library "think modern".)

With that new freedom, the changes that have been performed in the recent 10 month are too many to be listed and documented in each detail. (Only for module ALib Expressions , a detail list is given below.) Consequently, the adoption of user code might become a little more effort than with previous ALib updates, as many entities have been moved to a different place.

The following provides a high level list of changes.

  • Refactoring of the module structure: The former seven modules have been refactored to now 16 modules. With that, almost any type of the library found a new "home", respectively namespace. The modules now strictly obey to a well defined dependency relationship which is documented here.
  • New CMake build scripts support the selection and compilation of only a subset of the 16 modules into an so called ALib Distribution .
    For users of other build systems, the CMake scripts allow to generate source listings to determine the exact subset of library files needed for a built.
  • With the restructuring the code, also the documentation was restructured. Besides the complete reference documentation, ALib now has a separated general user manual along with 14 module-specific programmer manuals. (Two small modules do not have a dedicated programming manual, hence only reference documentation is available for those.)
  • New module ALib Characters was extracted from both, module ALib Strings and ALib Boxing . While it is rather small, it provides a good abstraction layer to mitigate general challenges when using characters, character arrays, string literals and 3rd-party string types with C++.
    A dedicated Programmer's Manual is available for this module.
  • Module ALib Boxing was completely rewritten. While the API for boxing and unboxing values remained almost unchanged, in the area of customization of boxing for user types as well as of the definition of box-functions, existing user code needs to be revised. Along with the code, the dedicated Programmer's Manual of module ALib Boxing was completely rewritten.
  • Module ALib Strings was refactored in respect to now building on ALib Characters . Apart from the former terminated string type TString, which is now named CString, code adoptions should be required mostly in the fields of adopting 3rd-party types to be transparently accepted as strings and to make 3rd-party types compatible (appendable) to class AString .
    Default character width of strings can now be adjusted to 1, 2 or 4 bytes. Tons of further small changes have been implemented, including a change of all internal TMP programming.
    This module's Programmer's Manual was also completely rewritten.
Module Expressions:
Apart from the many changes due to refactoring the library, explicit change information this time is only given for module ALib Expressions :
  • Added auto-cast option for casting arguments of unary operators (which was available only to binary operator and ternary operator Q ? T : F only).
  • Added auto-cast feature to helper class plugins::Calculus for easy implementation of custom type auto-casting.
    Added manual chapter 6.5.2 Implementing Auto-Casts Using Class Calculus to sample the use of this feature.
  • Changed name of ternary operator Q ? T : F when given with CompilerPlugin::CIAutoCast::Op from "?:" to "Q?T:F" to make it distinguishable from the binary "Elvis-operator".
  • Renamed fields DbgCallBackName and DbgCallBackNameRhs in CompilerPlugin , respectively in derived types, to use a lower case letter 'b'.
  • Changed field Calculus::FunctionEntry::ResultType to being a pointer to a sample box, instead of a sample box (shorter footprint and slightly faster).
  • Added static struct Signatures which contains expression function signatures for all built-in functions. On the one hand, this reduced the footprint of the library (slightly) and on the other hand these static objects can be also used by custom plug-ins (in case a matching signature is found in the list).
  • Renamed fields CastExpressionFunctionName and CastExpressionFunctionNameRhs to CIAutoCast::ReverseCastFunctionName , respectively CIAutoCast::ReverseCastFunctionNameRhs
  • Fixed internal assertions that had been raised with malformed expression input. In these instances, now exceptions of type Exceptions::SyntaxErrorExpectation are thrown.
  • Fixed the meta data of Exceptions::NestedExpressionResultTypeError to display the expected and given types correctly (had been reversed).
  • Removed class FunctionNameDescriptor and replaced it with new class Token . This has two compatibility consequences:
    • Custom expression plug-in resources have to be adopted to the new parsing format of identifier and function names.
    • Many built-in function abbreviations have changed to support abbreviation of single camel-case humps.
  • Added class ExpressionFormatter which is similar to existing PropertyFormatter , but supports the use of expressions instead of just simple property callbacks.
  • Removed division and modulo operators from compiler plug-in Arithmetics with boolean divisor type (not useful and dangerous in respect to division by zero exceptions).
  • Fixed minor formatting issues of program listings generated by VirtualMachine::DbgList .
  • Corrected a longer list of typos and small errors of the module's manual. Added some notes about how sample boxes of abstract types can be created.
PS:
We very much hope that this overhaul and "refactoring orgy" now finally led to a stable structure that will not dramatically change in the future. The foundation set in this release allows growth and extension of the library by new independent and optional ALib Modules , similar to modules ALox , ALib Expressions and ALib CLI .

We think that the library is now well prepared to support the future C++ language feature of modularization (see for example the current clang draft) without further need of heavy refactoring.

Version 1805, Revision 0, released May 12th, 2018

IMPORTANT INFORMATION: New C++ Fork Of ALib:
The C++ part of multi-language project ALox Logging Library has been forked into this project. The goal and consequences of this effort are:
  • Have a repository and website exclusively dedicated to ALib for C++.
  • Reverse the library nesting in the C++ Version: ALib here is now the main project, while ALox becomes one ALib Module .
  • Decouple the development and roadmaps of future ALib modules from Java and C# language versions of ALib /ALox .
General:
With the decoupling of the C++ version, the whole project structure has changed. This reaches from directory names to the CMake and IDE-specific project files provided.

These changes are not listed in detail here. Instead, for information about building this new version, users of previous versions should read the ALib Programmer's Manual and start "from scratch".

Support for preconfigured QTCreator project files was dropped.

Macros:
Module Core:
  • Removed virtual base class Ownable. Instead, class Owner now is templated. This allowed several classes to be non-virtual, for example ThreadLock or Lox .
  • Added method ThreadLock::Owner.
  • Renamed method DbgCountAcquirements to ThreadLock::CountAcquirements , removed its former parameter. The former behaviour can be accomplished using by comparing result of new method ThreadLock::Owner with Threads::CurrentThread.
  • Fixed infinite recursion with method Enum::IsType.
  • Added class Console.
  • Overhauled class MemoryBlocks. More changes to be expected in future versions.
  • Introduced StringTreeBlockAllocator and made class StringTree be able to use it. This allows very memory efficient allocations with StringTree in appropriate use cases.
Module Strings:
  • The underlying character type of all string classes became a template type. This lead to a complete overhaul of almost every type in namespace aworx::lib::strings. The changes of code are so dramatic that they can not be listed here completely. Nevertheless, user code should not be effected very much, because the now templated types have alias names that correspond to the former, non-templated types!
  • Added virtual method FormatterBase::Clone.
  • Removed static methods Formatter::AcquireDefault and Formatter::ReleaseDefault. Instead, a shared pointer holding a Formatter object is available with GetDefaultFormatter.
    The feature of resetting the default formatter with former method Formatter::ReleaseDefault was moved to now overloaded method Formatter::Acquire and therefore is now available more generally to all formatters.
  • Added compatibility with C++ 17 standard type std_string_view.
Module ALox:

As explained above, ALox has been made a module of ALib . (Before this release, the relationship was quite reverse: ALib then was the "underlying utility library" of ALox ).
With this, the namespace of ALox types has been renamed (moved) as well: from former "aworx::lox" to aworx::lib::lox.

Furthermore, used new allocation mechanics of class StringTree to efficiently allocate internal data in respect to the "language scopes" of ALox .

Module Expressions:

This release introduces new module ALib Expressions .

Module CLI:

This release introduces new module ALib CLI . However the programmer's manual of that module was not written, yet. Due to the lack of documentation, we can not really recommend to use this module. As we are using it with other projects already, the code itself is considered stable and tested.

Older Versions

All previous versions have been maintained as a part of multi-language project ALox Logging Library.

Please consult this project's Change-Log for information on changes since the initial release in May 2013.