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

Version 2510, Revision 0, released October 1st, 2025

The main decision that lead to the changes of this release, was dropping language support below C++20. With that, this release constitutes a major update of ALib and every single file of the library was touched.

The downside is: Users of ALib that for any reason cannot switch to C++20, have to continue working with the previous ALib release V2412.

Tested Platforms
The minimum required CMake version is 3.20. This version was successfully tested under the following platform and toolchain combinations:
  • GNU/Linux Arch 6.16.8, Clang++ 20.1.8, C++20/23, 32-Bit / 64-Bit, optional C++20 Module Support
    (This is the main development platform.)
  • GNU/Linux Arch 6.16.8, GNU C++ 15.2.1, C++20/23, 32-Bit / 64-Bit
  • WindowsOS 11, MSC 19.44 (Visual Studio 2026 Insiders, Platform v145), C++20, 32-Bit/64-Bit
  • WindowsOS 11, MinGW, 64-Bit, GCC 13.47, C++20
  • macOS Tahoe 26.0, Apple M2 / ARM64, Apple Clang Version 17.0.0, C++20/23, 64-Bit
  • Raspberry 3, aarch64, Cortex-A53, GNU C++ 12.2.0, C++20/23
  • Raspberry 4, aarch64, Cortex-A72, GNU C++ 12.2.0, C++20/23
  • Raspberry 4, armhf (32-bit), Cortex-A72, GNU C++ 12.2.0, C++20/23
C++20 Modules:
We added some (!) support for C++20 Modules. Because of this, we were forced to perform a complete overhaul of the library structure, the previously 17 "ALib Modules", are now split into 25! Thus, the structure and dependency graph of the existing ALib Modules has been changed.

We managed to retain the previous flexibility, allowing users to exclude specific "ALib Modules" from the build. This approach helps minimize both build times and the size of the resulting executable. However, due to technical reasons, two small changes have been made in this regard:

  • Module ALib Time is not selectable anymore. It will always be included in the ALib Build.
  • Module ALib Threads is now included in the build in case the new compiler-symbol ALIB_SINGLE_THREADED is not provided. (Before, this module was included using the now removed symbol ALIB_THREADS).

Also, by nature, all header files have changed (!), because with C++20 Modules we had to give up the previous "one class - one header" approach. But we consider the new header files much easier to use.

Please refer to the (rewritten) manual chapter 2. ALib Modules for all details about ALib Modules, C++-modules and header files.

Note
We consider the current state of the use of C++ 20 Modules by ALib to be in an alpha state. It works only with very recent clang compiler and we are all but satisfied with the results. We will observe the evolution of the language and the compilers and will adjust the ALib accordingly. But for now, we consider low-level libraries like ALib not being eligible for C++ 20 Modules.
We have created a blog-page dedicated to share our Observations Made When Shifting ALib to C++20 Modules.
C++20 Concepts
All of ALib is now free of (ugly) template meta programming using std::enable_if and uses new keywords concept and requires instead. (An overview of all concepts introduced by ALib is found here.)
The implications are:
  • Every std::enable_if and corresponding "helper-template-parameters" have been removed. Altogether 493 replacements across the library!
  • Removed almost all former template-meta-programming macros, as their use was mostly by C++20 concepts or similar built-in type traits. The names of the removed macros all started with ATMP_. Now, the two remaining macros were renamed to use prefix ALIB_ as all other macros do.
    The remaining macros are ALIB_TVALUE and ALIB_HAS_METHOD.
  • Changed the ALib naming conventions. Type-trait types, which had been prefixed with T_ are now instead suffixed by Traits. For example, this affects:
  • Helper structs using template metaprogramming, which formerly were named with the prefix TT_ have been replaced by modern idioms like concepts, type-aliases, etc. As an example, former types alib::characters::TT_CharArrayType and alib::characters::TT_ZTCharArrayType were replaced by concepts IsArray and IsZTArray along with type aliases Type and ZTType.
    Many more similar replacements have been performed. Please, consult the reference- and programmer's-manuals of the corresponding modules in case your code does not compile with a type prefixed T_, or TT_.
New Module Assert
This new module contains entities to raise ALib Assertions, ALib Warnings and other messages. It is implemented using the C++ standard libraries and its string-types. This replaces the former plug-in based concept implemented with now removed types Report and ReportWriter.
Likewise, the former plugin ALoxReportWriter was removed. However, as the new assertion system still supports a plug-in mechanism, module ALox now plugs into it with its new function ALoxAssertionPlugin.
The concepts are primarily made for internal use, but can be used by any software likewise. Thus, a corresponding Programmer's Manual is available.
New Module Bootstrap
The bootstrap process itself did not change. Nevertheless, all functionality is now gathered in the new module ALib Bootstrap.
Further General Changes
  • Renamed module ALib Configuration to ALib Variables. In fact, this should have happened with the last release already, where this module was rewritten
    from scratch.
  • Removed documentation of symbols ALIB_GDB_PP_FIND_POINTER_TYPES and ALIB_GDB_PP_SUPPRESS_CHILDREN (which had been discarded in the previous release already).
  • Added macro ALIB_WARNINGS_IGNORE_DEPRECATED.
  • Removed macros ALIB_FORCE_INLINE and ALIB_NO_RETURN.
  • Removed macro ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE because clang compiler became too strict with that flag and it was necessary just too often. Instead, the warning is now disabled globally.
  • Renamed macro ALIB_DEBUG_MONOMEN to ALIB_DEBUG_MEMORY and removed its responsibility from module ALib Monomem to let it have a general library association.
  • The use of clang's libc++ under GNU/Linux is now supported with the new CMake variable ALIB_CLANG_USE_LIBCPP, which is used with CMake function ALibSetCompilerAndLinker.
  • Added the compiler option /utf-8 for MSVC with the shipped project files.
Module Characters:
Modules EnumOps and EnumRecords:
Module Strings:
  • The default-constructor of class TCString now does not initialize an instance to be nulled anymore. Instead, no initialization is performed. This is now in alignment with the default constructor of base class TString.
  • Pointers to instances of appendable types are not accepted by the append-methods of class AString anymore. If desired, the pointer type has to be made appendable explicitly (optionally in parallel to the value type).
  • The following classes had been subtypes of the removed type TFormat and were moved out:

    And, class TField has now two different implementations, depending on the inclusion of the module ALib Boxing in the ALib Build.

  • With the inclusion of the header ALib.Compatibility.StdStrings.H, specializations of C++20 struct std::formatter are now given. This allows to use ALib string types with function std::format.
  • Changed inner types and a few method names of classes String and AString to gain compatibility with C++ container algorithms.
  • Added assign operator to class LocalString. (Before, assignment was inefficient as the move constructor was used.)
Module Boxing:
  • With the use of C++20 concepts and some relaxed rules in respect to C++ unions and their use in constexpr contexts with that language version, module ALib Boxing was overhauled.
  • Some former techniques of customizations (to keep things constexpr) of boxing could be removed and thus simplified. If this breaks your code, please consult the updated ALib Module Boxing - Programmer's Manual Programmer's Manual
  • Methods GetRecord and TryRecord of class Enum have been moved to namespace-level with functions GetRecord and TryRecord.
Module Containers:
Changed inner types and a few method names of classes List to gain compatibility with C++ container algorithms.
Module ALox:

Version 2412, Revision 0, released December 13th, 2024

Platforms
The minimum required CMake version is now 3.20. This version was successfully tested under the following platform and toolchain combinations:
  • GNU/Linux Arch 6.12.1, GNU C++ 14.2.1 / Clang++ 18.1.8, C++ 17/20/23, 32-Bit / 64-Bit
    (This is the main development platform.)
  • WindowsOS 10/11, MSC 19.42 (Visual Studio 2022), C++ 17/20, 32-Bit / 64-Bit
  • WindowsOS 10/11, MinGW, GCC 13.47 C++ 17/20, 64-Bit
  • macOS Sequoia 15.2, Apple M2 / ARM64, Apple Clang Version 16.0.0, C++ 17/20/23, 64-Bit
  • Raspberry 3, ARM, 64-bit OS, GNU C++ 12.2.0, C++ 17/20/23
  • Raspberry 4, ARM, 64-bit OS, GNU C++ 12.2.0, C++ 17/20/23
General Changes
  • Optimized ALib Homepage for mobile access and several smaller documentation improvements.
  • Renamed singleton types derived of class lang::Camp along the scheme "XYZCamp".
  • Extended CMake script that defines the library filename to reflect various feature selections.
  • Fixed names of various global (namespace) variables to "UPPER_SNAKE_CASE". (As stated in the project's naming conventions.)
  • Rewritten pretty printers for ALib types and GNU Debugger (gdb).
  • Removed support for Cotire-builds because this tool itself lost support.
Preprocessor Symbols/Macros:
Library Core Types
Module Characters:
  • Moved all static methods of type alib::characters::CharArray to namespace level. The then empty type got removed.
  • Added AlignedCharArray.
  • With both these changes, the header files and their names got refactored.
Module Time:
  • Added overloaded constructors and operators allowing shorter code when code mixes ALib types and with std::chrono-types. Especially, this allows using C++ literals defined in std::literals::chrono_literals with the ALib types.
Module Threads:
  • This was largely revised and now reflects the decision to drop support of standards below C++ 17.
  • Added dependency to moduleALib Time.
  • Replaced former types ThreadLockNR and ThreadLock with types
  • The former "safeness control"-features were dropped.
  • Extended macros ALIB_LOCK and ALIB_LOCK_WITH, with corresponding new siblings: ALIB_LOCK_RECURSIVE,
    ALIB_LOCK_SHARED,
    ALIB_LOCK_RECURSIVE_WITH, and
    ALIB_LOCK_SHARED_WITH.
  • Removed class SmartLock.
  • Added class Promise.
Module ThreadModel (New):
This is a new module that introduces a proposal of how to organize threads in an application.
Module Boxing:
  • Fixed support for boxing of type long double. The rationale here was rather a bug: Without us noticing, the alignment of type Box had increased to 2 x alignof(void*) (on some systems). Consequently, the size of class Box had increased to 32 bytes (with 64-bit systems affected from the bug), in contrast to the 24 bytes that are documented (8 alignment bytes had been accidentally added).
  • Added methods Box::ExportType, Box::ExportValue, overloaded methods Box::Import, as well as a constructor that accepts a pair of an exported type and value.
  • Former class Boxes is templated and called TBoxes with type definitions BoxesHA (equivalent to the prior type) and BoxesPA.
Module Enums:
  • Added namespace function enums::bitwise::HasOneOf.
Module Strings:
Module Containers (New):
With the introduction of the generic allocation mechanisms (noted above), the container types became allocator-agnosic and this way were moved from module ALib Monomem to the new module "Containers". Due to the close relationship of topics, both modules share a joint Programmer's Manual. Other changes are:
Module Monomem:
Largely extended and refactored monotonic allocation facilities. To reach this goal, namespace alib::lang (which is always included in any ALib Distribution) received new general allocation facilities, which use heap allocation (as noted above).
Note that the changes in this module are far-reaching and can't all be listed here. Please refer to the Programmer's Manual, which is almost completely rewritten.
  • Types that implement the std::allocator contract are now allocator-agnostic and have been moved out of this module and into namespace alib::lang. The types are now:
  • The container types are now allocator-agnostic and have been moved to the new module ALib Containers.
  • Type MonoAllocator now is just a type definition into templated type TMonoAllocator. The template parameter allows the new concept of allocator chaining.
  • Added the new class TLocalAllocator which uses stack memory for (the first) allocation buffer.
  • Added the new class PoolAllocator, which implements a general approach to memory recycling applicable to a wide range of use-cases.
  • Moved namespace function alib::monomem::Destruct to alib::lang::Destruct.
  • Former class SelfContained has been extended with automatic pointer mechanics and was renamed to TSharedMonoVal.
  • Renamed type definition StdContMA to SCAMono and introduced sibling definitions StdVectorMono, StdVectorPool, StdListMono, StdListPool, StdDequeMono, and StdDequePool.
  • Added AString type definitions for MonoAllocator as well as for new allocator type PoolAllocator. Those are: AStringMA, AStringPA, ComplementAStringMA, ComplementAStringPA, StrangeAStringMA, StrangeAStringPA, NAStringMA, NAStringPA, WAStringMA, WAStringPA, XAStringMA} and XAStringPA}.
    In turn, previous type TMAString and its former type definitions MAString, ComplementMAString, StrangeMAString, NMAString, WMAString, and XMAString were removed.
  • If the compiler symbol ALIB_DEBUG_ALLOCATIONS is given, class MonoAllocator, as well as the two new allocators and type HeapAllocator, now add padding bytes around allocations and test for validity when memory is freed. Furthermore, freed memory is overwritten to detect illegal memory access early. Likewise method MonoAllocator::Reset now overwrites the released memory with this special debug mode.
  • Removed MonoAllocator::dbgCheckGlobalAllocatorLock in favor of using the new, generic concept of critical sections.
  • Removed convenience functions monomem::AcquireGlobalAllocator and monomem::ReleaseGlobalAllocator.
Camp BaseCamp:
  • Class lang::Exception is now copyable and movable. While it is still recommended to catch references to instances of class Exception, instances may now, for example, be collected in lists.
  • Method Exception::Format now appends the CallerInfo to the end of each exception entry.
  • Renamed and refactored the former class Directory to lang::system::Path. The type was never really well-developed, and this was also marked in its docs. Now it is in a quite useful state for the first time.
  • SPFormatter is no of new type SharedPtr (was std::shared_ptr before).
  • Virtual method lang::format;Formatter::Default now returns a value of type SPFormat.
  • Removed static method Formatter::GetDefault() and instead gave public access to member lang::format::Formatter::Default. The former method Formatter::ReplaceDefault() was not even defined, and this bug became now obsolete.
  • Changed field lang::format::FormatterPythonStyle::Sizes to being a pointer which by default points to the new member lang::format::FormatterPythonStyle::SizesDefaultInstance. This allows attaching an external instance.
  • Fixed lang::format::FormatterPythonStyle to correctly use tab stops when new-line characters are given natively with '\n'. (Before, this worked only when those were given with escape sequence "\\n".)
  • Class lang::format::FormatterPythonStyle now allows nested curly braces "{...}" within its fields. This enables custom format string definitions (implemented with box-function lang::format::FFormat) to contain curly braces.
  • Several exceptions thrown by formatters now contain the argument type of the placeholder in question. With debug-builds, this information is displayed if the exception is formatted.
  • Added type-definition lang::system::PathCharType, which aliases C++ standard type std::filesystem::path::value_type. With that several string aliases like lang::system::PathString, or lang::system::PathStringMA have been added, and class lang::system::Path uses this type as its underlying character type.
Camp Config:
This ALib Camp was rewritten from scratch. This, of course, implies huge changes of the using code. The good news is that the use of configuration variables is now much easier and straight forward, and it is now suited to cover an even wider range of use cases. In fact, the former implementation was one of the few remainders in ALib resulting from its origin in languages Java and C# and thus was inefficient and not following modern C++ style at all.
The Programmer's Manual of this module was likewise rewritten and now contains step-by-step tutorial sections.
Camp Files:
  • Added compiler symbol ALIB_FILES_FORCE_STD_SCANNER and preprocessor symbol ALIB_FILES_SCANNER_IMPL.
  • Added class File which inherits the cursor type of class FTree. This allows interfacing with entries in the file tree on different levels and paves the way for future features of this type that manipulate files on the system.
  • Implemented box-function lang::format::FFormat for new class File to support the output of file data with formatter lang::format::FormatterPythonStyle. The implementation makes use of method File::Format, which therefore defines the format strings' syntax likewise for the python formatter.
  • Added new class alib::files,TextFile "files,TextFile".
Camp Expressions:
  • Former std::shared_ptr SPExpression is now of new type SharedVal and was renamed to Expression. What was Expression before, is now named ExpressionVal.
  • Various smaller changes and optimizations with class Scope. Removed former vector Resources as only Scope::NamedResources seemed useful.
Camp ALox:

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.
By 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.
  • 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.
  • Special module ALibDistribution was renamed to 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 the completely overhauled Programmer's Manual of the library.

Core library types:

  • Fixed a bug im method alib::lang,CLZ0(TIntegral) "lang,CLZ0(TIntegral)" to return sizeof(TIntegral) * 8 in case the given value is zero, just as documented. It returned 0 before.
  • Added functions alib::lang,CTZ(TIntegral) "lang,CTZ(TIntegral)" and alib::lang,CTZ0(TIntegral) "lang,CTZ0(TIntegral)" using intrinsics.
  • Added functions alib::lang,UpperMask<TWidth,TIntegral>(),UpperMask<TWidth,TIntegral> "lang,UpperMask<TWidth,TIntegral>(),UpperMask<TWidth,TIntegral>" and alib::lang,UpperMask<TIntegral>(ShiftOpRHS),UpperMask<TIntegral> "lang,UpperMask<TIntegral>(ShiftOpRHS),UpperMask<TIntegral>".
  • Removed function BitCounterWidth<TIntegral>() and replaced it with alib::lang,Log2OfSize,Log2OfSize<TIntegral>() "lang,Log2OfSize,Log2OfSize<TIntegral>()", which returns the former functions result -1.
  • Changed functions alib::lang,LowerMask<TIntegral>(ShiftOpRHS),LowerMask<TIntegral> "lang,LowerMask<TIntegral>(ShiftOpRHS),LowerMask<TIntegral>" 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 alib::lang,bitsofval "lang,bitsofval".
  • Added class lang::TBitSet to new header lang/bitset.hpp, which is a more sophisticated replica of std::bitset.
  • Added type definition enums::EnumBitSet which allows to use new type lang::TBitSet conveniently with enumeration types.

CommonEnums:

  • Added common enum alib::lang,Recursive "lang,Recursive".

Module Enums:

Module Time:

  • Added method alib::time,TimePointBase::Reset "time,TimePointBase::Reset".

Module Strings:

  • Added type definition alib::strings,TString::CharType "strings,TString::CharType".
  • Added template parameter TCheck to method alib::strings,TString::Equals,String::Equals "strings,TString::Equals,String::Equals" to allow omitting checks for nulled strings if appropriate.
  • Added method alib::strings,TAString::DetectLength "strings,TAString::DetectLength".
  • Added utility class alib::strings,TStringLengthResetter "strings,TStringLengthResetter".
  • Aggregated boolean flags in class NumberFormat to new enum type alib::strings,NumberFormatFlags "strings,NumberFormatFlags".

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 alib::monomem,HashTable "monomem,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 alib::monomem,GlobalAllocator "monomem,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 alib::monomem,StringTree "monomem,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 monomem::StringTree::ConstructRootValue. and monomem::StringTree::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 alib::monomem,StringTree::Cursor "monomem,StringTree::Cursor". (Ok, we did this once already the other way round. Well...)
  • Added types alib::monomem,StringTree::ConstCursor "monomem,StringTree::ConstCursor" and alib::monomem,StringTree::ConstRecursiveIterator "monomem,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 alib::monomem,StringTree::TCursor::AssemblePath "monomem,StringTree::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 alib::monomem,StringTreeNamesDynamic "monomem,StringTreeNamesDynamic". On the same token, added debug statistic variables alib::monomem,DbgStatsStringTreeNames "monomem,DbgStatsStringTreeNames" and alib::monomem,DbgStatsStringTreeNameOverflows "monomem,DbgStatsStringTreeNameOverflows" to support choosing a reasonable internal buffer size, which is application dependent.

Module BASECAMP:

  • As explained above, Basecamp is a new module aggregating the contents of other former modules.
  • Added parameter nf to lang::format::FFormat::Signature to allow custom formatting functions of boxes to access these configuration values of the formatter.
  • Added enum class lang::format::ByteSizeUnits and format types lang::format::ByteSizeIEC and lang::format::ByteSizeSI.

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 type enums::T_EnumIsIterable, macro ALIB_ENUMS_MAKE_ITERABLE and also header file 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:

  • Added the field lang::resources::LocalResourcePool::DbgResourceLoadObserver and updated the corresponding manual chapter.

Module Enums:

  • Added three more namespace functions for bitwise defined enumeration types: enums::bitwise::CountElements, enums::bitwise::ToBitwiseEnumeration and enums::bitwise::ToSequentialEnumeration.

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}
    • alib::strings::util,Token "strings::util,Token"
    • ALib string types when wrapped in std::reference_wrapper.
    • Added convenience method alib::boxing,Box::UnboxMutable "boxing,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 alib::strings,TAString::Reverse,AString::Reverse "strings,TAString::Reverse,AString::Reverse" and underlying implementation alib::characters,CharArray<TChar>::Reverse "characters,CharArray<TChar>::Reverse".
  • Added checks for field ostream with output methods of class alib::strings,compatibility::std::StringWriter "strings,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 alib::strings,TAString,AString "strings,TAString,AString" not also reset the capacity, but also the length of the moved string to 0.
  • Method alib::strings,TString::WStringLength,String::WStringLength "strings,TString::WStringLength,String::WStringLength" now, in case of failure, returns the strings' unconverted length instead of -1.

Module Time:

  • Added method alib::time,TimePointBase::Unset "time,TimePointBase::Unset".
  • Added methods alib::time::TimePointBase,Duration::SetMinimum "time::TimePointBase,Duration::SetMinimum" and alib::time::TimePointBase,Duration::SetMaximum "time::TimePointBase,Duration::SetMaximum".
  • Renamed method TimePointBase::Raw to alib::time,TimePointBase::ToRaw "time,TimePointBase::ToRaw".
  • Added method alib::time,TimePointBase::SetFromRaw "time,TimePointBase::SetFromRaw".
  • Renamed method TimePointBase::NativeValue to alib::time,TimePointBase::Export "time,TimePointBase::Export". Changed its signature to being const and changed return value to a copy of the internal value instead of a reference to it.
  • Added method alib::time,TimePointBase::Import "time,TimePointBase::Import".

Module Threads:

  • Changed signature of most methods of class alib::threads,Thread "threads,Thread" to being virtual.
  • Added method alib::threads,Thread::Terminate "threads,Thread::Terminate", which has to be called prior to destructing a thread.
  • Added enum alib::threads,Thread::State "threads,Thread::State" and method alib::threads,Thread::GetState "threads,Thread::GetState", which replace removed boolean field Thread::isAliveFlag and method Thread::IsAlive.
  • Added static method alib::threads,Thread::YieldToSystem "threads,Thread::YieldToSystem"
  • Added static methods alib::threads,Thread::Sleep "threads,Thread::Sleep" and alib::threads,Thread::SleepUntil "threads,Thread::SleepUntil"
  • Added class alib::threads,Sleeper "threads,Sleeper".
  • Improved debug assertions of class alib::threads,ThreadLockNR "threads,ThreadLockNR"

Module Monomem:

  • Fixed method alib::monomem,List::ElementAt "monomem,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) "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 monomem::util::FixedCapacityVector and type definition FixedSizePriorityQueue.
  • Removed method HashTable::Rehash. See reference documentation for the rationale.
  • Added parameter reference to methods alib::monomem,HashTable::Reserve "monomem,HashTable::Reserve", alib::monomem,HashTable::ReserveRecyclables "monomem,HashTable::ReserveRecyclables" and alib::monomem,StringTree::ReserveRecyclables "monomem,StringTree::ReserveRecyclables".
  • Constructor of alib::monomem,StringTree "monomem,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 alib::monomem,HashTable::EmplaceOrAssign "monomem,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 lang::format::FormatterStdImpl::writeStringPortion (performance optimization).
  • lang::format::FormatterStdImpl now performs custom formatting whenever a custom boxing function lang::format,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:

  • Changed the format of resourced variable declarations.
  • Fixed a bug that caused utility method config::Configuration::PreloadVariables to overwrite existing variables with default values.
  • Method config::Configuration::Load now adds the default value to the given variable instance, also when no default configuration plug-in is added.

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 lang::system::CalendarDate.

Module ALox:

  • Fixed special shortcut header 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 alib::lox,Lox::IsActive "lox,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 alib::lox::loggers,TextFileLogger "lox::loggers,TextFileLogger" now tests file for possible access during construction. Errors may be evaluated with new field alib::lox::loggers,TextFileLogger::LastSystemError "lox::loggers,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 alib::expressions,ExpressionRepository "expressions,ExpressionRepository".
    A standard implementation for it is provided with alib::expressions,StandardRepository "expressions,StandardRepository". Implementations are to be set to new field alib::expressions,Compiler::Repository "expressions,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 expressions::util::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 Enums and ALib Resources, and is now 100% located in 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 the 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_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, lang::resources::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 alib::threads,ThreadLock "threads,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:

  • Added methods alib::characters,CharArray::ToUpper(TChar*, integer) "characters,CharArray::ToUpper(TChar*, integer)" and alib::characters,CharArray::ToLower(TChar*, integer) "characters,CharArray::ToLower(TChar*, integer)".

Module Boxing:

  • It is now allowed to invoke alib::boxing,Box::TypeID "boxing,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 alib::boxing,Boxes "boxing,Boxes":
    • Now optionally accepts a alib::monomem,MonoAllocator "monomem,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 alib::boxing,Boxes::Add "boxing,Boxes::Add" now return a reference to the invoked object.
  • Renamed namespace function EnumValue to enums::UnderlyingIntegral.
  • Renamed method Enum::Value to alib::boxing,Enum::Integral "boxing,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 alib::boxing,DbgBoxing::GetKnownVTables "boxing,DbgBoxing::GetKnownVTables" was added and along with that, method alib::boxing,DbgBoxing::GetKnownFunctionTypes "boxing,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 alib::strings,TString,String "strings,TString,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 alib::strings,TString::indexOfString "strings,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 alib::boxing::detail,DbgStringTable "boxing::detail,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 alib::strings,TAString,AString "strings,TAString,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 alib::monomem,StringTree "monomem,StringTree" from module ALib Strings to module ALib Monomem 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 alib::strings,AllocateCopy "strings,AllocateCopy" and alib::strings,DeleteString "strings,DeleteString".
  • Moved methods ConsumeEnum, ConsumeEnumBitwise and ConsumeEnumOrBool from class alib::strings,TSubstring,Substring "strings,TSubstring,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 corresponding new manual section.
  • 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 DbgAssertSingleThreaded in debug-compilations, that asserts if a second thread visits library code that needs protection.
  • Re-implemented bigger parts of alib::threads,ThreadLock "threads,ThreadLock" with slight changes in its interface.

Module Monomem (formerly Memory):

  • Renamed module Memory to Monomem, which is now found in namespace aworx::lib::monomem and received an own Programmer's Manual.
  • Class MemoryBlocks was renamed to alib::monomem,MonoAllocator "monomem,MonoAllocator" and received tons of changes and extensions. Among them:
    • Renamed method MonoAllocator::Construct to alib::monomem,MonoAllocator::Emplace "monomem,MonoAllocator::Emplace".
    • Changed (simplified) the internal allocation code of object alib::monomem,MonoAllocator::Chunk "monomem,MonoAllocator::Chunk".
    • Added overloaded methods alib::monomem,MonoAllocator::TakeSnapshot "monomem,MonoAllocator::TakeSnapshot" and alib::monomem,MonoAllocator::Reset(const Snapshot&) "monomem,MonoAllocator::Reset(const Snapshot&)" which allow to reset the allocator to a certain state and dispose intermediate objects.
  • Added struct alib::monomem,SelfContained "monomem,SelfContained".
  • Added class alib::monomem,List "monomem,List".
  • Moved class alib::monomem,StringTree "monomem,StringTree" from module ALib Strings, performing a 100% overhaul.
  • Added class alib::monomem,HashTable "monomem,HashTable" and with it type definitions
  • Added class alib::monomem,TMAString "monomem,TMAString".
  • Added classes alib::monomem,StdContMA "monomem,StdContMA", alib::monomem,StdContMAOptional "monomem,StdContMAOptional" and alib::monomem,StdContMARecycling "monomem,StdContMARecycling" to support monotonic allocation with C++ standard containers.
  • Added allocator instance alib::monomem,GlobalAllocator "monomem,GlobalAllocator", which is used during bootstrap by various modules.
  • Added compiler symbol ALIB_DEBUG_MONOMEM to enable debug-features for this module.
  • Added a verbose Programmer's Manual for this module.

Module Resources:

  • Overhauled resource management:
    • Programmer's Manual was rewritten.
    • Renamed type Resources to lang::resources::ResourcePool and made it pure abstract interface type.
    • Renamed methods of lang::resources::ResourcePool to more precise and better readable names.
    • Removed ability to store non-static resource strings.
    • Added new type lang::resources::LocalResourcePool as the default interface implementation
    • Added new type lang::resources::ConfigResourcePool an optional interface implementation.
    • Adopted changes in type Module.
    • Adopted changes in library's Programmer's manual chapter.
  • Removed all previously included functionality of the former concept "ALib Enum Meta Data", which was completely rewritten to new concept ALib Enum Records and located in module Enums.
  • Uses monotonic allocation for resource management.
  • Removed class ResourceString.
  • Fixed a bug that prevented to add resources for common enum types, if module Config was not included in the ALib Distribution.

Module Results:

  • Adopted concept ALib Enum Records.
  • Changed class results::Message to derive from class alib::boxing,Boxes "boxing,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 alib::monomem,SelfContained "monomem,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 lang::format::Formatter::Acquire now returns an internal container of type Boxes, which optionally can be used to collect formatting arguments. If it is used, new methodlang::format::Formatter::FormatArgs(AString&) allows using this list.
  • Overloaded methods methodlang::format::Formatter::FormatArgs to 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 lang::format::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 lang::format::FormatterPythonStyle to optionally specify the quote character(s) that an argument should be surrounded by.
  • Removed creation of class alib::boxing,Boxes "boxing,Boxes" with method lang::format::Formatter::Format(AString, const TArgs&...). (This was accidentally inserted and totally superfluous.)

Module Configuration:

  • Adopted concept ALib Enum Records.
  • Class config::Variable now inherits new struct alib::monomem,SelfContained "monomem,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 config::Variable as well as method lang::config::Variable::Declare now accepts a single alib::boxing,Box "boxing,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 alib::boxing,Boxes "boxing,Boxes".
  • Class config::InMemoryPlugin was rewritten and changes adopted by derived type config::IniFile. It now uses monotonic allocation and shows better performance. Various changes in the rather internal interface are not listed here.
  • Added method lang::config::IniFile::AddResourcedSectionComments, which replaces a former less flexible approach to add resourced (externalized) comments to sections, when they get created programatically.
  • Added field lang::config::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 alox.hpp is now a shortcut to alox.hpp, which now only includes things needed to perform basic debug- and release-log operations.
    Class alib::lox,ALox "lox,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 "alox/aloxmodule.hpp" has to be explicitly included.
    To allow the reduction, class alib::lox,Lox "lox,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 lang::format::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 alib::lox,Lox::InternalDomains "lox,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 alib::monomem,MonoAllocator "monomem,MonoAllocator" to type alib::expressions,Compiler "expressions,Compiler" and by using new container types of module ALib Monomem wherever possible.
  • Changed method name Scope::Clear to alib::expressions,Scope::Reset "expressions,Scope::Reset".
  • Renamed field Scope::nestedExpressionStack to alib::expressions,Scope::NestedExpressions "expressions,Scope::NestedExpressions"
  • Moved the compile-time scope object from class alib::expressions,detail::Program "expressions,detail::Program" to alib::expressions,Expression::ctScope "expressions,Expression::ctScope".
  • Simplified class alib::expressions::plugins,Calculus "expressions::plugins,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 Multithreaded 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 alib::monomem,TMAString "monomem,TMAString".
  • Renamed enum flag AllowBitwiseBooleanOperations to alib::expressions::Compilation,AllowBitwiseBooleanOperators "expressions::Compilation,AllowBitwiseBooleanOperators".
  • Resourced (externalized) names of built-in types alib::expressions,Types "expressions,Types".

Compatibility Headers:

  • Moved overloads of operator<< given with 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.
  • 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 alib::strings,TAString,AString "strings,TAString,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 alib::expressions,plugins::Calculus "expressions,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 alib::expressions,CompilerPlugin "expressions,CompilerPlugin", respectively in derived types, to use a lower case letter 'b'.
  • Changed field alib::expressions::plugins,Calculus::FunctionEntry::ResultType "expressions::plugins,Calculus::FunctionEntry::ResultType" to being a pointer to a sample box, instead of a sample box (shorter footprint and slightly faster).
  • Added static struct alib::expressions,Signatures "expressions,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 alib::expressions::plugins::Calculus,CIAutoCast::ReverseCastFunctionName "expressions::plugins::Calculus,CIAutoCast::ReverseCastFunctionName", respectively alib::expressions::plugins::Calculus,CIAutoCast::ReverseCastFunctionNameRhs "expressions::plugins::Calculus,CIAutoCast::ReverseCastFunctionNameRhs".
  • Fixed internal assertions that had been raised with malformed expression input. In these instances, now exceptions of type alib::expressions,Exceptions::SyntaxErrorExpectation "expressions,Exceptions::SyntaxErrorExpectation" are thrown.
  • Fixed the meta data of alib::expressions,Exception::NestedExpressionResultTypeError "expressions,Exception::NestedExpressionResultTypeError" to display the expected and given types correctly (had been reversed).
  • Removed class FunctionNameDescriptor and replaced it with new class alib::strings::util,Token "strings::util,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 expressions::util::ExpressionFormatter which is similar to existing lang::format::PropertyFormatter, but supports the use of expressions instead of just simple property callbacks.
  • Removed division and modulo operators from compiler plug-in alib::expressions::plugins,Arithmetics "expressions::plugins,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 alib::expressions::detail,VirtualMachine::DbgList "expressions::detail,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 alib::threads,ThreadLock "threads,ThreadLock" or Lox.
  • Added method ThreadLock::Owner.
  • Renamed method DbgCountAcquirements to alib::threads,ThreadLock::CountAcquirements "threads,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.