MBO, a C++20 library

This C++20 library provides some general useful building blocks and integrates with Google's Abseil library.

The library is tested with Clang and GCC on Ubuntu and MacOS (arm) using continuous integration: .

The C++ library is organized in functional groups each residing in their own directory.

• Config
  • namespace mbo::config
  • mbo/config:config_cc, mbo/config/config.h
    • Custom Bazel flag --//mbo/config:limited_ordered_max_unroll_capacity which controls the maximum unroll size for LimitedOrdered and thus LimitedMap and LimitedSet.
    • Custom Bazel flag --//mbo/config:require_throws which controls whether MBO_CONFIG_REQUIRE throw exceptions or use crash logging (the default False or 0). This mostly affects containers.
  • mbo/config:require_cc, mbo/config/require.h
    • Marcos MBO_CONFIG_REQUIRE(condition, message) which allows to check a condition and either throw an exception or crash with Abseil FATAL logging. The behavior is controlled by --//mbo/config:require_throws.
• Container
  • namespace mbo::container
  • mbo/container:any_scan_cc, mbo/container/any_scan.h
    • class AnyScan: A container type independent iteration view - or scan over the container.
    • class ConstScan: A container type independent iteration view for const value_types.
    • class ConvertingScan: A container scanner that allows for conversions.
    • function MakeAnyScan: Helper function to create AnyScan instances.
    • function MakeConstScan: Helper function to create ConstScan instances.
    • function MakeConvertingScan: Helper function to create ConvertingScan instances.
  • mbo/container:convert_container_cc, mbo/container/convert_container.h
    • conversion struct ConvertContainer simplifies copying containers to value convertible containers.
  • mbo/container:limited_map_cc, mbo/container/limited_map.h
    • class LimitedMap: A space limited, constexpr compliant map.
  • mbo/container:limited_options_cc, mbo/container/limited_options.h
    • class LimitedOptions: A compile time configuration option for LimitedSet and LimitedMap.
  • mbo/container:limited_set_cc, mbo/container/limited_set.h
    • class LimitedSet: A space limited, constexpr compliant set.
  • mbo/container:limited_vector_cc, mbo/container/limited_vector.h
    • class LimitedVector: A space limited, constexpr compliant vector.
• Diff
  • namespace mbo::diff
  • mbo/diff:unified_dff_cc, mbo/diff/unified_diff.h
    • class UnifiedDiff: A class that implements unified-diffing.
  • mbo/diff:unified_diff
    • binary unfied_diff: A binary that performs a unified-diff on two files.
  • mbo/diff:diff_bzl, mbo/diff/diff.bzl
    • bzl-macro difftest: A test rule that compares an output versus a golden file.
• Files
  • namespace mbo::files
  • mbo/file:artefact_cc, mbo/file/artefact.h
    • struct Artefact: Holds information about a file (its data content, name, and modified time).
  • mbo/file:file_cc, mbo/file/file.h
    • function GetContents: Reads a file and returns its contents or an absl::Status error.
    • function GetMTime: Returns the last update/modified time of a file or an absl::Status error.
    • function GetMaxLines: Reads at most given number of text lines from a file or returns absl::Status error.
    • function IsAbsolutePath: Returns whether a given path is absolute.
    • function JoinPaths: Join multiple path elements.
    • function JoinPathsRespectAbsolute: Join multiple path elements respecting absolute path elements.
    • function NormalizePath: Normalizes a path.
    • function Readable: Returns whether a file is readable or an absl::Status error.
    • function SetContents: Writes contents to a file.
  • mbo/file:glob_cc, mbo/file/glob.h
    • struct mbo::file::Glob2Re2Options: Control conversion of a glob pattern into a RE2 pattern.
    • struct mbo::file::GlobEntry: Stores data for a single globbed entry (file, dir, etc.).
    • struct mbo::file::GlobOptions: Options for functions Glob2Re2 and Glob2Re2Expression.
    • enum mbo::file::GlobEntryAction: Allows GlobEntryFunc to control further glob progression.
    • type mbo::file::GlobEntryFunc: Callback for acceptable glob entries.
    • function mbo::file::GlobRe2: Performs recursive glob functionality using a RE2 pattern.
    • function mbo::file::Glob: Performs recursive glob functionality using a fnmatch style pattern.
    • program glob: A recursive glob, see glob --help.
  • mbo/file/ini:ini_file_cc, mbo/file/ini/ini_file.h
    • class IniFile: A simple INI file reader.
• Hash
  • namespace mbo::hash
  • mbo/hash:hash_cc, mbo/hash/hash.h
    • function simple::GetHash(std::string_view): A constexpr capable hash function.
• Log
  • namespace mbo::log
  • mbo/log:log_timing_cc, mbo/log/log_timing.h
    • functoin mbo::log::LogTiming([args]) a simple timing logger.
• Mope
  • namespace mbo::mope
  • The MOPE templating engine. Run bazel run //mbo/mope -- --help for detailed documentation.
  • mbo/mope
    • binary mope.
  • mbo/mope:mope_cc, mbo/mope/mope.h
    • class Template: The mope template engine and data holder.
  • mbo/mope:ini_cc, mbo/mope/ini.h
    • function ReadIniToTemplate: Helper to initialize a mope Template from an INI file.
  • mbo/mope:mope_bzl, mbo/mope/mope.bzl
    • bzl-rule mope: A rule that expands a mope template file.
    • bzl-macro mope_test: A test rule that compares mope template expansion against golden files. This supports clang-format and thus can be used for source-code generation and verification.
• Status
  • namespace mbo::status
  • mbo/status:status_builder_cc, mbo/status/status_builder.h
    • class StatusBuilder which allows to extend the message of an absl::Status.
  • mbo/status:status_cc, mbo/status/status.h
    • function GetStatus allows to convert types to an absl::Status.
  • mbo/status:status_macros_cc, mbo/status/status_macros.h
    • macro MBO_ASSIGN_OR_RETURN: Macro that simplifies handling functions returning absl::StatusOr<T>.
    • macro MBO_MOVE_TO_OR_RETURN: Macro that simplifies handling functions returning absl::StatusOr<T> where the result requires commas, in particular structured bindings.
    • macro MBO_RETURN_IF_ERROR: Macro that simplifies handling functions returning absl::Status or absl::StausOr<T>.
• Strings
  • namespace mbo::strings
  • mbo/strings:indent_cc, mbo/strings/indent.h
    • function DropIndent: Converts a raw-string text block as if it had no indent.
    • function DropIndentAndSplit: Variant of DropIndent that returns the result as lines.
  • mbo/strings:numbers_cc, mbo/strings/numbers.h
    • function mbo::strings::BigNumber: Convert integral number to string with thousands separator.
    • function mbo::strings::BigNumberLen: Calculate required string length for BigNumer.
  • mbo/strings:parse_cc, mbo/strings/parse.h
    • function ParseString: Parses strings respecting C++ and custom escapes as well as quotes (all configurable).
    • function ParseStringList: Parses and splits strings respecting C++ and custom escapes as well as quotes (all configurable).
  • mbo/strings:split_cc, mbo/strings/split.h
    • struct mbo::strings::AtLast: Allows `absl::StrSplit' to split on the last occurrence of a separator.
  • mbo/strings:strip_cc, mbo/strings/strip.h
    • function ConsumePrefix: Removes a prefix from a std::string (like absl::ConsumePrefix).
    • function ConsumeSuffix: Removes a suffix from a std::string (like absl::ConsumeSuffix).
    • function StripPrefix: Removes a prefix from a std::string&& (like absl::StripPrefix).
    • function StripSuffix: Removes a suffix from a std::string&& (like absl::StripSuffix).
    • struct StripCommentsArgs: Arguments for StripComments and StripLineComments.
    • function StripComments: Strips comments from lines.
    • function StripLineComments: Strips comments from a single line.
    • struct StripParsedCommentsArgs: Arguments for StripParsedComments and StripParsedLineComments.
    • function StripParsedComments: Strips comments from parsed lines.
    • function StripLineParsedComments: Strips comments from a single parsed line.
• Testing
  • namespace mbo::testing
  • mbo/testing:matchers_cc, mbo/testing/matchers.h
    • gMock-Matcher CapacityIs which checks the capacity of a container.
    • gmock-matcher WhenTransformedBy which allows to compare containers after transforming them. This sometimes allows for much more concise comparisons where a golden expectation is already available that only differs in a simple transformation.
  • mbo/testing:status_cc, mbo/testing/status.h
    • gMock-matcher IsOk: Tests whether an absl::Status or absl::StatusOr is absl::OkStatus.
    • gMock-matcher IsOkAndHolds: Tests an absl::StatusOr for absl::OkStatus and contents.
    • gMock-matcher StatusIs: Tests an absl::Status or absl::StatusOr against a specific status code and message.
    • gmock-matcher StatusHasPayload: Tests whether an absl::Status or absl::StatusOr payload map has any payload, a specific payload url, or a payload url with specific content.
    • gmock-matcher StatusPayloads Tests whether an absl::Status or absl::StatusOr payload map matches.
    • macro MBO_ASSERT_OK_AND_ASSIGN: Simplifies testing with functions that return absl::StatusOr<T>.
    • macro MBO_ASSERT_OK_AND_MOVE_TO: Simplifies testing with functions that return absl::StatusOr<T> where the result requires commas, in particular structured bindings.
• Types
  • namespace mbo::types
  • mbo/types:cases_cc, mbo/types/cases.h
    • meta-type Cases: Allows to switch types based on conditions.
    • meta-type CaseIndex: Evaluates the first non zero case (1-based, 0 if all zero).
    • meta-type IfThen: Helper type to generate if-then Cases types.
    • meta-type IfElse: Helper type to generate else Cases which are always true and must go last.
    • meta-type IfFalseThenVoid: Helper type that can be used to skip a case.
    • meta-type IfTrueThenVoid: Helper type to inject default cases and to ensure the required type expansion is always possible.
  • mbo/types:compare_cc, mbo/types/compare.h
    • comparator mbo::types::CompareLess which is compatible to std::Less but allows container optimizations.
  • mbo/types:container_proxy_cc, mbo/types/container_proxy.h
    • struct mbo::types::ContainerProxy which allows to add container access to other types including smart pointers of containers.
  • mbo/types:extend_cc, mbo/types/extend.h
    • crtp-struct Extend: Enables extending of struct/class types with basic functionality.
    • crtp-struct ExtendNoDefault Like Extend but without default extender functionality.
    • crtp-struct ExtendNoPrint Like Extend but without Printable and Streamable extender functionality.
    • namespace extender
      • extender-struct AbslStringify: Extender that injects functionality to make an Extended type work with abseil format/print functions. See Stringify for various API extension points.
      • extender-struct AbslHashable: Extender that injects functionality to make an Extended type work with abseil hashing (and also std::hash).
      • extender-struct Comparable: Extender that injects functionality to make an Extended type comparable. All comparators will be injected: <=>, ==, !=, <, <=, >, >=.
      • extender-struct Printable:
        • Extender that injects functionality to make an Extended type get a std::string ToString() const function which can be used to convert a type into a std::string.
        • The output is a comma separated list of field values, e.g. { 25, 42 }.
        • If available (Clang 16+) this function prints field names { .first = 25, .second = 42 }.
      • extender-struct Streamable: Extender that injects functionality to make an Extended type streamable. This allows the type to be used directly with std::ostreams.
  • mbo/types:no_destruct_cc, mbo/types/no_destruct.h
    • struct NoDestruct<T>: Implements a type that allows to use any type as a static constant.
    • Mainly, this prevents calling the destructor and thus prevents termination issues (initialization order fiasco).
  • mbo/types:opaque_cc, mbo/types/opaque.h
    • struct mbo::types::OpaquePtr an opaque alternative to std::unique_ptr which works with forward declared types.
    • struct mbo::types::OpaqueValue an OpaquePtr with direct access, comparison and hashing which will not allow a nullptr.
    • struct mbo::types::OpaqueContainer an OpaqueValue with direct container access.
  • mbo/types:ref_wrap_cc, mbo/types/ref_wrap.h
    • template-type RefWrap<T>: similar to std::reference_wrapper but supports operators -> and *.
  • mbo/types:required_cc, mbo/types/required.h
    • template-type Required<T>: similar to RefWrap but stores the actual type (and unlike std::optional cannot be reset).
  • mbo/types:stringify_cc, mbo/types/stringify.h
    • class Stringify a utility to convert structs into strings.
    • function StringifyWithFieldNames a format control adapter for Stringify.
    • struct StringifyOptions which can be used to control Stringify formatting.
    • API extension point type MboTypesStringifySupport which enables Stringify support even if not otherwise enabled (disables Abseil stringify support in Stringify).
    • API extension point type MboTypesStringifyDisable which disables Stringify support. This allows to prevent complex classes (and more importantly fields of complex types) from being printed/streamed using Stringify
    • API extension point type MboTypesStringifyDoNotPrintFieldNames which if present disables field names in Stringify.
    • API extension point function MboTypesStringifyFieldNames which adds field names to Stringify.
    • API extension point function MboTypesStringifyOptions which adds full format control to Stringify.
  • mbo/types:stringify_ostream_cc, mbo/types/stringify_ostream.h
    • operator std::ostream& operator<<(std::ostream&, const MboTypesStringifySupport auto& v) - conditioanl automatic ostream support for structs using Stringify.
  • mbo/types:traits_cc, mbo/types/traits.h
    • type alias ContainerConstIteratorValueType returned the value-type of the const_iterator of a container.
    • concept ContainerIsForwardIteratable determines whether a types can be used in forward iteration.
    • concept ContainerHasEmplace determines whether a container has emplace.
    • concept ContainerHasEmplaceBack determines whether a container has emplace_back.
    • concept ContainerHasInsert determines whether a container has insert.
    • concept ContainerHasPushBack determines whether a container has push_back.
    • concept ContainerHasForwardIterator determines whether a container has begin, end and std::forward_iterator compliant iterators.
    • concept ContainerHasInputIterator determines whether a container has begin, end and std::input_iterator compliant iterators.
    • type alias GetDifferenceType is either set to the type's difference_type or std::ptrdiff_t.
    • concept HasDifferenceType determines whether a type has a difference_type.
    • concept IsAggregate determines whether a type is an aggregate.
    • concept IsCharArray determines whether a type is a char* or char[] related type.
    • concept IsDecomposable determines whether a type can be used in static-bindings.
    • concept IsInitializerList determines whether a type is `std::initializer type.
    • concept IsBracesConstructibleV determines whether a type can be constructe from given argument types.
    • concept IsOptional determines whether a type is a std::optional type.
    • concept IsPair determines whether a type is a std::pair type.
    • concept IsSet determines whether a type is a std::set type.
    • concept IsSameAsAnyOfRaw / NotSameAsAnyOfRaw which determine whether type is one of a list of types.
    • concept IsSmartPtr determines whether a type is a std::shared_ptr, std::unique_ptr or std::weak_ptr.
      • Can be extended with other smart pointers through IsSmartPtrImpl.
    • concept IsTuple determines whether a type is a std::tuple type.
    • concept IsVariant determines whether a type is a std::variant type.
    • concept IsVector determines whether a type is a std::vector type.
  • mbo/types:template_search_cc, mbo/types/template_search.h:
    • template struct BinarySearch implements templated binary search algorithm.
    • template struct LinearSearch implements templated linear search algorithm.
    • template struct ReverseSearch implements templated reverse linear search algorithm.
    • template struct MaxSearch implements templated linear search for last match algorithm.
  • mbo/types:tstring_cc, mbo/types/tstring.h
    • struct tstring: Implements type tstring a compile time string-literal type.
    • operator operator"" _ts: String literal support for Clang, GCC and derived compilers.
  • mbo/types:tuple_cc, mbo/types/tuple.h
    • template struct mbo::types::TupleCat which concatenates tuple types.

In addition some Bazel macros are implemented that are not direct part of the library:

• bzl:archive.bzl
  • http_archive: Simple wrapper that tests whether the archive was already loaded.
  • github_archive: Specialized archive wrapper that supports github that supports tagged releases or commits.

Installation and requirements

This repository requires a C++20 compiler (in case of MacOS XCode 15 is needed). This is done so that newer features like std::source_location can be used.

The project only comes with a Bazel BUILD.bazel file and can be added to other Bazel projects.

The project is formatted with specific clang-format settings which require clang 16+ (in case of MacOs LLVM 16+ can be installed using brew). For simplicity in dev mode the project pulls the appropriate clang tools and can be compiled with those tools using bazel [build|test] --config=clang ....

WORKSPACE

Checkout Releases or use head ref as follows:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
  name = "com_helly25_mbo",
  url = "https://github.com/helly25/mbo/archive/refs/heads/main.tar.gz",
  # See https://github.com/helly25/mbo/releases for releases.
)

MODULES.bazel

Check Releases for details. All that is needed is a bazel_dep instruction with the correct version.

bazel_dep(name = "helly25_mbo", version = "0.0.0")

Unlike the WORKSPACE installation the MODULES.bazel installation from source checkout, the above Bazel-Central-Registry installation does not provide the LLVM tools and thus does not come with its own compiler. This is due to a restriction in Bazel's ability to handle toolchains when Bazel uses MODULES (--enable_bzlmod as opposed to --enable_workspace). Nonetheless all versions, all versions can be compiled with GCC 11+, Clang 17+ on Ubuntu and MacOs as enforced by CI. Other platforms and compilers are likely to work as well. However, Windows lacks some of the necessary tools and the library as well as its build system mostly assume Unix-style file and path names. That unfortunately means that on Windows some code cannot even be built.

Presentations

Practical Production-proven Constexpr API Elements

Presented at C++ On Sea 2024, this presentation covers the theory behind:

• mbo::hash::simple::GetHash,
• mbo::container::LimitedVector,
• mbo::container::LimitedMap, and
• mbo::container::LimitedSet.

Slides are available at: