MSL

MSL (Marty Support Library) is a header-only C++20 utility library focused on practical helpers with minimal integration friction.

Feature Map

Header	Purpose
msl/assert.h	Assert helpers and test exceptions (check_assert, test_assert, test_error).
msl/bench.h	Lightweight benchmarking/evaluation helpers.
msl/cast.h	Truncation/integral conversion helpers with checked paths.
msl/file_ptr.h	RAII wrapper around FILE* with read/write helpers.
msl/macro.h	Public MSL_FOR_* loop and test macros.
msl/pool.h	Thread-safe shared object pool (shared_pool<T>).
msl/ptr.h	Pointer ownership wrappers (scoped_shared_ptr, no_owner, observer_ptr).
msl/random.h	Random generators, number utilities, and container sampling.
msl/range.h	Range/xrange and indexed iteration helpers.
msl/traits.h	Type traits for contiguous/raw template constraints (msl::traits::*).
msl/utils.h	String and container utility helpers.
msl/util.h	Compatibility forwarding header to msl/utils.h.
msl/legacy.h	Opt-in legacy compatibility helpers (minmax, bind/random-shuffle/mem_fun wrappers).
msl/msl.h	Aggregate include for all MSL headers.

Installation

1) Manual include

Copy include/msl/ into your include path and use:

#include <msl/msl.h>

2) CMake FetchContent

include(FetchContent)

FetchContent_Declare(
  MSL
  GIT_REPOSITORY https://github.com/martysama0134/MSL.git
  GIT_TAG main
)
FetchContent_MakeAvailable(MSL)

target_link_libraries(your_target PRIVATE msl::msl)

3) CMake install + find_package

Build/install:

cmake -S . -B build/install -DMSL_BUILD_TESTS=OFF
cmake --build build/install
cmake --install build/install --prefix /your/prefix

Consume:

find_package(MSL CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE msl::msl)

Project Layout

• include/msl/: public header-only library.
• tests/: deterministic CI regression tests and header smoke builds.
• examples/: compile-verified example programs (optional build via MSL_BUILD_EXAMPLES).
• docs/: compatibility, migration, and release validation docs.
• legacy/vs/: legacy Visual Studio solution/project and demo-heavy test assets.

Compiler and Platform Support

Platform	Compiler/toolchain	Status
Windows	Visual Studio 2022 (MSVC v143)	First-class
Linux	GCC 14+ (libstdc++)	First-class
Linux	Clang 19+ (libstdc++14+ or libc++19+)	First-class
FreeBSD 14/15	Default cc / c++ (Clang 18/19)	Release-gated manual validation

MSL targets C++20 and requires std::format plus std::ranges as baseline dependencies in v4.0+.

Current CI quality gates:

• windows-msvc (blocking)
• linux-gcc14-libstdcxx (blocking)
• linux-clang19-libstdcxx (blocking)
• linux-clang19-libcxx (blocking)
• linux-clang-asan-ubsan (blocking)
• alpine-clang (non-blocking)

Quick Start

String helpers

#include <msl/utils.h>
#include <iostream>

int main() {
    auto parts = msl::string_split("alpha::beta::gamma", "::");
    std::cout << parts.size() << "\n"; // 3
}

Safe numeric conversion

#include <msl/cast.h>

int main() {
    auto v = msl::integral_cast<int>(42.0); // ok
    // msl::integral_cast<int>(42.5); // throws msl::truncate_error
}

Shared object pool

#include <msl/pool.h>

struct Obj { int value{}; };

int main() {
    auto pool = msl::shared_pool<Obj>::create();
    auto h = pool->acquire();
    h->value = 123;
}

API Notes and Safety Caveats

• file_ptr:
  • open(std::string_view, ...) now opens through owned null-terminated strings.
  • reopening via open(...) first closes any currently owned file handle.
  • write(fmt, args...) keeps legacy printf formatting compatibility.
  • write_fmt(fmt, args...) provides C++20 std::format formatting.
  • byte-oriented write helpers return bytes written.
  • string_read(char[], n) is defined for n == 0 (no-op) and always null-terminates for n > 0.
• cast:
  • checked floating-to-integral paths reject NaN, inf, out-of-range values, and fractional values for integral_cast.
• shared_pool:
  • shared_pool<T>::handle::get() now correctly returns T*.
  • shared_pool remains thread-safe via internal mutex-protected operations.
• traits:
  • msl::traits::is_contiguous_v<T> and msl::traits::is_raw_v<T> are available for template routing and raw-write constraints.
• utils:
  • to_lower_in_place / to_lower are intentionally ASCII/language-neutral right now.
  • Unicode-aware lowercase helper(s) may be added later with distinct API names.
  • format_grouped_number(value, separator) provides simple digit grouping for integral values.
• MSL_FOR_* macros are supported public API.
• legacy:
  • <msl/legacy.h> is an explicit opt-in compatibility header.
  • legacy helpers are exposed in msl namespace and are not included by <msl/msl.h>.
  • legacy helpers do not extend namespace std.

Legacy Policy

Use <msl/legacy.h> only for compatibility migrations. It is intentionally separate from the default aggregate include to keep modern usage lean.

#include <msl/legacy.h>

int main() {
    const auto v = msl::minmax(10, 42, 0); // auto-swaps bounds, returns 10
}

Build and Test

Presets:

cmake --preset dev
cmake --build --preset dev
ctest --preset dev

Shell helpers:

./test_build.sh
./test_run.sh

CI runs deterministic tests from tests/ only. Legacy demo-heavy test sources remain in legacy/vs/msl/test_*.cpp for local/manual use.

Examples

Configure/build examples:

cmake -S . -B build/examples -DMSL_BUILD_TESTS=ON -DMSL_BUILD_EXAMPLES=ON
cmake --build build/examples

Example executables:

• msl_example_string_split
• msl_example_safe_cast
• msl_example_shared_pool
• msl_example_file_ptr_io

Versioning and Release Notes

• Current release target: v4.0.0.
• Changelog: CHANGELOG.md
• Migration notes: docs/MIGRATION_v4.md
• Compatibility policy: docs/COMPATIBILITY.md
• Legacy API map: docs/LEGACY_API_MAP.md
• Release validation gate: docs/RELEASE_VALIDATION.md
• Legacy Visual Studio solution: legacy/vs/msl_tests.sln

License

MSL is distributed under the MIT License. See LICENSE.