diff --git a/.github/workflows/benchmarks.yaml b/.github/workflows/benchmarks.yaml index e8e58947..af77b126 100644 --- a/.github/workflows/benchmarks.yaml +++ b/.github/workflows/benchmarks.yaml @@ -12,7 +12,7 @@ on: jobs: build: - name: Build and run benchmarks + name: Build and Run Benchmarks (Smoke Test) runs-on: ubuntu-24.04 steps: @@ -33,12 +33,12 @@ jobs: -DBUILD_BENCHMARKS=ON -DBENCH_INCLUDE_BGL=ON -DCMAKE_BUILD_TYPE=Release continue-on-error: false - - name: Build the benchmarks + - name: Build the Benchmarks run: | cmake --build build_bench/ -j$(nproc) continue-on-error: false - - name: Execute the smoke test + - name: Execute the Smoke Test run: | ./build_bench/benchmarks/cpp-gl-bench \ --benchmark_repetitions=1 --benchmark_display_aggregates_only=true \ diff --git a/.github/workflows/clang.yaml b/.github/workflows/clang.yaml index b96c953f..f1ef35a1 100644 --- a/.github/workflows/clang.yaml +++ b/.github/workflows/clang.yaml @@ -12,7 +12,7 @@ on: jobs: build: - name: Build and run tests + name: Build and Run Tests (Clang) runs-on: ubuntu-24.04 steps: @@ -27,12 +27,12 @@ jobs: cmake -B build_clang -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC continue-on-error: false - - name: Build test executable + - name: Build Tests run: | cmake --build build_clang/ -j$(nproc) continue-on-error: false - - name: Run tests + - name: Run Tests run: | ./build_clang/tests/gl ./build_clang/tests/hgl diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml new file mode 100644 index 00000000..fbcd8ea3 --- /dev/null +++ b/.github/workflows/documentation.yaml @@ -0,0 +1,88 @@ +name: Documentation + +on: + pull_request: + branches: + - "*" + push: + tags: + - "v*" + +permissions: + contents: write + +jobs: + build-and-deploy: + name: Build & Deploy Documentation + runs-on: ubuntu-24.04 + + steps: + - name: Check out repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + submodules: recursive + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.14" + + - name: Install system dependencies + run: sudo apt-get update && sudo apt-get install doxygen -y + + - name: Install Python dependencies (uv) + run: | + pip install uv + uv sync + + - name: Validate Internal Project Versions + run: | + VERSION=$(uv run python scripts/check_version.py) + echo "project version = $VERSION" + echo "VERSION=$VERSION" >> $GITHUB_ENV + + - name: Validate Git Tag (Deploy Only) + if: github.event_name == 'push' + run: | + VERSION_TAG="${GITHUB_REF_NAME}" + echo "git version tag = $VERSION_TAG" + if [[ "$VERSION_TAG" != "v$VERSION" ]]; then + echo "Error: Tag mismatch: git version tag = $VERSION_TAG, project version: v$VERSION" + exit 1 + fi + + - name: Build Docs (PR Validation Only) + if: github.event_name == 'pull_request' + run: make build-docs + + # See: https://api.github.com/users/github-actions%5Bbot%5D + - name: Configure Git (Deploy Only) + if: github.event_name == 'push' + run: | + git config --local user.name "github-actions[bot]" + git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com" + + - name: Determine if Latest Tag (Deploy Only) + if: github.event_name == 'push' + run: | + CURRENT_VERSION="v${VERSION}" + git fetch --tags --force + ALL_TAGS=$(git tag | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V) + LATEST_TAG=$(echo "$ALL_TAGS" | tail -n 1) + + if [ "$CURRENT_VERSION" = "$LATEST_TAG" ]; then + echo "DEPLOY_LATEST=true" >> $GITHUB_ENV + else + echo "DEPLOY_LATEST=false" >> $GITHUB_ENV + fi + + - name: Deploy with mike (Latest) + if: github.event_name == 'push' && env.DEPLOY_LATEST == 'true' + run: | + make docs TAGS="--push --update-aliases v${VERSION} latest" + uv run mike set-default --push latest + + - name: Deploy with mike (Older Version) + if: github.event_name == 'push' && env.DEPLOY_LATEST == 'false' + run: make docs TAGS="--push v${VERSION}" diff --git a/.github/workflows/format.yaml b/.github/workflows/format.yaml index ef55687f..106e66b3 100644 --- a/.github/workflows/format.yaml +++ b/.github/workflows/format.yaml @@ -25,7 +25,7 @@ jobs: - name: Set up python uses: actions/setup-python@v5 with: - python-version: "3.12" + python-version: "3.14" - name: Test formatting shell: bash diff --git a/.github/workflows/gpp.yaml b/.github/workflows/gpp.yaml index e2e125a3..78979aab 100644 --- a/.github/workflows/gpp.yaml +++ b/.github/workflows/gpp.yaml @@ -12,7 +12,7 @@ on: jobs: build: - name: Build and run tests + name: Build and Run Tests (G++) runs-on: ubuntu-24.04 steps: @@ -27,12 +27,12 @@ jobs: cmake -B build_gcc -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC continue-on-error: false - - name: Build test executable + - name: Build Tests run: | cmake --build build_gcc/ -j$(nproc) continue-on-error: false - - name: Run tests + - name: Run Tests run: | ./build_gcc/tests/gl ./build_gcc/tests/hgl diff --git a/.github/workflows/licence.yaml b/.github/workflows/licence.yaml index 551a38f5..780bfa10 100644 --- a/.github/workflows/licence.yaml +++ b/.github/workflows/licence.yaml @@ -11,7 +11,7 @@ on: jobs: build: - name: Test code formatting + name: Test License Comments runs-on: ubuntu-24.04 steps: @@ -23,7 +23,7 @@ jobs: with: python-version: "3.12" - - name: Test formatting + - name: Validate Licence Comments shell: bash run: | python3 scripts/check_licence.py diff --git a/Doxyfile b/Doxyfile index e6204d6f..27dc4b92 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1028,7 +1028,7 @@ EXCLUDE_PATTERNS = *.mk # wildcard * is used, a substring. Examples: ANamespace, AClass, # ANamespace::AClass, ANamespace::*Test -EXCLUDE_SYMBOLS = std doctest doctest_detail_test_suite_ns detail *::detail +EXCLUDE_SYMBOLS = std doctest doctest_detail_test_suite_ns detail *::detail impl *::impl # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include diff --git a/Makefile b/Makefile index bffa4526..d1ac8ec8 100644 --- a/Makefile +++ b/Makefile @@ -1,18 +1,25 @@ # Default to 'dev' if TAGS is not specified on the command line TAGS ?= dev -.PHONY: docs serve-docs clean-docs clean +.PHONY: docs build-docs serve-docs clean-docs clean -# Example usage: `make docs TAGS="v2.0.0 latest --update-aliases"` +# Target for CI Pull Requests: Just builds to verify everything works (no deployment) +build-docs: clean-docs + @echo "==> Building MkDocs documentation..." + doxygen Doxyfile + uv run python docs/scripts/gen_concept_docs.py --config docs/config/concepts.json --xml documentation/xml --out docs/cpp-gl + uv run mkdocs build --strict + +# Example usage: `make docs TAGS="v2.0.0 latest --update-aliases --push"` docs: clean-docs - @echo "==> Deploying MkDocs documentation locally via mike (Tags: $(TAGS))..." + @echo "==> Deploying MkDocs documentation (Tags: $(TAGS))..." doxygen Doxyfile uv run python docs/scripts/gen_concept_docs.py --config docs/config/concepts.json --xml documentation/xml --out docs/cpp-gl uv run mike deploy $(TAGS) @echo "==> Documentation deployed to local gh-pages branch." serve-docs: docs - @echo "==> Serving versioned MkDocs documentation locally via mike..." + @echo "==> Serving versioned MkDocs documentation..." uv run mike serve clean-docs: diff --git a/README.md b/README.md index 6f440f3b..d431e53c 100644 --- a/README.md +++ b/README.md @@ -4,108 +4,181 @@

-
-
[![G++](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml) [![Clang++](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml) + +
+ +
+ [![Code Formatting](https://github.com/SpectraL519/cpp-gl/actions/workflows/format.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/format.yaml) [![Benchmarks Smoke Test](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml) +[![changelog](https://img.shields.io/badge/changelog-blue.svg?logo=github)](https://github.com/SpectraL519/cpp-gl/releases)

+## Documentation + +The complete, versioned documentation, including detailed tutorials, quick start guides, and architectural overviews, is hosted online: + +**[Explore the CPP-GL Documentation](https://spectral519.github.io/cpp-gl/latest/)** + +
+ ## Overview -- The goal of the project was to create a higlhy customizable, intuitive and easy to work with graph library for the modern C++ standards. -- The `CPP-GL` library's implementation relies solely on the C++ standard library (it does not require installing any additional tools) and is designed to be compatible with the C++ standard tools, e.g. range-based loops, std algorithms, the [ranges library](https://en.cppreference.com/w/cpp/ranges), stream operations, etc. -- The library relies heavily on [concepts](https://en.cppreference.com/w/cpp/language/constraints) to acheive abstraction instead of interfaces and abstract classes to minimize the overhead associated with virtual tables and dynamic dispatch. +CPP-GL is a highly customizable, intuitive, and concept-driven graph and hypergraph library designed for modern C++ standards. -> [!NOTE] -> `v1.0.*` and `v1.0-prerelease-*` versions of the library have been developed as the Bachelor of Engineering project at the *Wrocław University of Science and Technology* -> -> Faculty: *W04N - Faculty of Information and Communication Technology* -> -> Field of study: *Algorithmic Computer Science* +Designed strictly around modern C++ paradigms, the library heavily leverages templates and concepts to deliver an API that is exceptionally fast, generic, and type-safe. It relies solely on the C++ standard library, meaning it requires no external dependencies and integrates perfectly with modern C++ tools such as range-based loops, the `` library, standard algorithms, stream operations, and more. -
+
-## Table of content +## Module Architecture: GL vs. HGL -- [Overview](#overview) -- [Table of content](#table-of-content) -- [Installing the library](#installing-the-library) -- [CMake integration](#cmake-integration) -- [Documentation - TODO](#documentation---todo) -- [Dev notes - TODO](#dev-notes---todo) -- [Compiler support](#compiler-support) -- [Licence](#licence) +To accommodate different mathematical models without compromising API clarity or performance, the library is strictly partitioned into two primary modules: -
+- **GL (Graph Library):** The core module dedicated to standard graphs. It handles both directed and undirected topologies where edges represent connections between exactly two vertices. It provides a comprehensive suite of utilities including structural generators, graph modifiers, and a broad spectrum of classical graph algorithms. +- **HGL (Hypergraph Library):** A specialized module dedicated to hypergraphs, where a single hyperedge represents a higher-order connection between an arbitrary number of vertices. It features generalized traversal algorithms and incidence-based memory models tailored for complex, multi-way relationships. -## Installing the library +
-The use the `CPP-GL` library in your project you can download the source code from the [releases](https://github.com/SpectraL519/cpp-gl/releases) page and add the `/include` path to the include directories of your project. +## Core Features -
+Because both modules share the same fundamental design philosophy, they offer a unified, symmetrical feature set tailored to their respective mathematical domains: -## CMake integration +- **Shared Zero-Cost Infrastructure:** By relying on C++20 concepts instead of virtual interfaces and dynamic dispatch, CPP-GL eliminates vtable overhead while enforcing strict compile-time contracts. Crucially, the **HGL module is built strictly on top of the GL module**, directly reusing its core infrastructure (ID types, traits, memory structures) to ensure maximum code reuse, while allowing the GL module to remain completely standalone for standard graph use cases. +- **Unified Topology APIs:** The `gl::graph` and `hgl::hypergraph` classes offer consistent interfaces that completely abstract away the underlying memory models. Users can seamlessly swap between different backend representations without rewriting traversal logic, property accesses, or algorithm calls. +- **Flexible Memory Layouts:** The library provides a comprehensive suite of memory-efficient representations. Users can choose between dynamic container-based layouts (Lists and Matrices) and highly optimized, cache-friendly contiguous array structures (Flat Lists and Flat Matrices). The HGL module further extends this by allowing users to specify the orientation of the memory models to optimize generalized incidence queries. +- **Customizable Element Properties:** Vertices, edges, and hyperedges can carry arbitrary, user-defined payloads. Whether assigning standard metric weights and colors or attaching complex, application-specific data structures, the library's traits system ensures that property injection and access remain strictly type-safe and performant. +- **Extensible Algorithmic Engines:** The library features a strictly decoupled algorithm design. Powerful, generic search templates serve as the underlying engines, allowing custom algorithms to be built on the fly by simply injecting zero-cost callbacks. Built upon these generic engines is a rich, out-of-the-box library of concrete algorithms—covering everything from classic pathfinding to advanced, multi-way reachability semantics for directed hypergraphs. +- **Robust I/O Facilities:** Native serialization and formatting tools make it simple to pipe topologies directly to and from standard C++ streams and files. Both the GL and HGL modules share a unified set of stream options for visual output, while relying on dedicated, easily parsable flat-text formats (GSF and HGSF) to ensure fast and predictable data serialization. -The `CPP-GL` library can also be included in a `CMake` project by adding the following to the `CMakeLists.txt` file of your project: +
-```cmake -cmake_minimum_required(VERSION 3.12) +## Compiler Support + +| Compiler | Min version | +| :-: | :-: | +| GNU G++ | 14 | +| Clang | 18 | + +> [!NOTE] +> +> Although currently the project has been properly verified using only the G++ and Clang compilers, it should work fine with other compilers with C++23 support like MSVC. +
+ +## Installation & Integration + +CPP-GL is a header-only template library. It can be integrated into a project either by directly including the headers or via CMake. + +### Option A: CMake `FetchContent` (Recommended) + +The easiest way to integrate CPP-GL is to fetch it directly from the GitHub repository during the CMake configuration phase: + +```cmake +cmake_minimum_required(VERSION 3.14) project(my_project LANGUAGES CXX) -# Include FetchContent module include(FetchContent) -# Fetch the CPP-GL library FetchContent_Declare( cpp-gl - GIT_REPOSITORY https://github.com/SpectraL519/cpp-gl.git - GIT_TAG # here you can specify the desired tag or branch + GIT_REPOSITORY [https://github.com/SpectraL519/cpp-gl.git](https://github.com/SpectraL519/cpp-gl.git) + GIT_TAG # Specify the desired version tag, branch, or specific commit. ) FetchContent_MakeAvailable(cpp-gl) -# Define the executable for the project add_executable(my_project main.cpp) set_target_properties(my_project PROPERTIES - CXX_STANDARD 23 # or newer + CXX_STANDARD 23 # The CPP-GL library requires C++23. CXX_STANDARD_REQUIRED YES ) -# Link against the cpp-gl library target_link_libraries(my_project PRIVATE cpp-gl) ``` -
+### Option B: Including the Headers Directly -## Documentation - TODO +If CMake is not being used, simply download the desired version of the library from the [Releases Page](https://github.com/SpectraL519/cpp-gl/releases) and add the `include` directory of the library to the project via the `-I/include` flag. -
+
-## Dev notes - TODO +## Benchmarks -
+Performance and zero-cost abstraction are primary goals of this library. A comprehensive evaluation suite built on top of **Google Benchmark** provides a structured way to measure, filter, and report the library's performance across various graph algorithms and memory layouts. -## Compiler support +For detailed performance metrics, configuration instructions (including BGL integration), and CLI usage, please refer to the **[Benchmarks Guide](benchmarks/README.md)**. -| Compiler | Min version | -| :-: | :-: | -| GNU G++ | 14 | -| Clang | 18 | +
+ +## Developer Notes + +To build the testing and documentation suites locally, follow the guides below. + +### Running Tests + +The library features a comprehensive test suite powered by **Doctest** and orchestrated via CMake. The test executables for both the `gl` and `hgl` modules can be built and run as follows: + +```bash +# Configure the project with tests enabled +cmake -B build -DBUILD_TESTS=ON + +# Build the test executables (replace with the core count) +cmake --build build/ -j + +# Execute the tests +./build/tests/gl +./build/tests/hgl +``` + +### Code Formatting + +The project enforces strict code formatting using `clang-format-18`. A custom Python script is provided to streamline the formatting process across the repository. + +To format the entire repository: + +```bash +python scripts/format.py -exe clang-format-18 +``` + +To format only the files modified in the last commit: + +```bash +python scripts/format.py -m -exe clang-format-18 +``` > [!NOTE] -> Although currently the project has been properly verified using only the G++ and Clang compilers it should work fine with other compilers with C++23 support like MSVC. +> +> If `clang-format-18` is your system's default, you can omit the `-exe` flag. -
+### Building the Documentation + +The documentation is generated using Doxygen (for XML extraction), a custom Python script for concept parsing, and MkDocs (via `mike` for versioning). The process is automated via a Makefile. + +To build and serve the documentation locally: + +```bash +make serve-docs +``` + +To clean the documentation build directories: +```bash +make clean-docs +``` + +> [!NOTE] +> +> The documentation build scripts rely on **[uv](https://docs.astral.sh/uv/)** to simplify Python dependency management within the project. Ensure `uv` is installed on the system before attempting to build the documentation. + +
-## Licence +## License -The `CPP-GL` project uses the [MIT Licence](https://mit-license.org/) which can be found in the [LICENCE](/LICENSE.md#mit-licence) file +The `CPP-GL` project uses the [MIT License](https://mit-license.org/) which can be found in the [LICENSE](LICENSE.md) file. diff --git a/benchmarks/README.md b/benchmarks/README.md index 22f9e3ae..c6fdbfd9 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -14,7 +14,7 @@ This directory contains the performance evaluation suite for the CPP-GL library. ## Building the Benchmarks -To configure and build the benchmark executable, use the following standard CMake commands: +To configure and build the benchmark executable, use the following standard CMake commands from the project root: ```shell cmake -B build_bench -DBUILD_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release @@ -30,6 +30,7 @@ cmake -B build_bench -DBUILD_BENCHMARKS=ON -DBENCH_INCLUDE_BGL=ON -DCMAKE_BUILD_ ``` > [!NOTE] +> > BGL comparative benchmarks are only defined for specific benchmark suites where a direct equivalent exists in Boost.
diff --git a/docs/gl/architecture.md b/docs/gl/architecture.md index 3f41936c..ac525521 100644 --- a/docs/gl/architecture.md +++ b/docs/gl/architecture.md @@ -23,17 +23,17 @@ The [**gl::graph_traits**](../cpp-gl/structgl_1_1graph__traits.md) struct config 1. **Directionality**: Directed vs. Undirected. 2. **Vertex Properties**: The data payload attached to each vertex. 3. **Edge Properties**: The data payload attached to each edge. -4. **Implementation Tag**: The underlying memory layout (e.g., Adjacency List). +4. **Representation Tag**: The underlying memory layout (e.g., Adjacency List). 5. **ID Type**: The integer type used for internal indexing (defaults to `std::uint32_t`). To reduce boilerplate, the library provides several generic type aliases for the most common configurations: - Based on the directional tag: - - [**gl::directed_graph**](../cpp-gl/group__GL-Core.md#typedef-directed_graph) - - [**gl::undirected_graph**](../cpp-gl/group__GL-Core.md#typedef-undirected_graph) + - [**gl::directed_graph**](../cpp-gl/group__GL-Core.md#typedef-directed_graph) + - [**gl::undirected_graph**](../cpp-gl/group__GL-Core.md#typedef-undirected_graph) -- Based on the implementation tag: +- Based on the representation tag: - [**gl::list_graph**](../cpp-gl/group__GL-Core.md#typedef-list_graph) - [**gl::flat_list_graph**](../cpp-gl/group__GL-Core.md#typedef-flat_list_graph) @@ -139,7 +139,7 @@ for (auto neighbor_id : graph.neighbor_ids(source_id)) { // (3)! ## Graph Representation Models -Choosing the correct memory layout is critical for algorithmic performance. CPP-GL abstracts this choice entirely behind the `ImplTag`, allowing you to swap layouts without altering a single line of traversal code. +Choosing the correct memory layout is critical for algorithmic performance. CPP-GL abstracts this choice entirely behind the `ReprTag`, allowing you to swap layouts without altering a single line of traversal code. ### Fundamental Representations @@ -161,21 +161,21 @@ Consider the following graph: CPP-GL currently categorizes its memory layouts into two primary families based on their underlying memory allocation strategy. -> [!NOTE] All representation model tag types are defined in the `gl::impl` namespace. +> [!NOTE] All representation model tag types are defined in the `gl::repr` namespace. #### Standard Models Heap-allocated, nested structures that prioritize flexibility and dynamic structural modification. -- [**list_t**](../cpp-gl/structgl_1_1impl_1_1list__t.md): A standard Adjacency List model implemented using traditional nested containers (e.g., `std::vector>`). -- [**matrix_t**](../cpp-gl/structgl_1_1impl_1_1matrix__t.md): A standard Adjacency Matrix model implemented using traditional nested containers. +- [**list_t**](../cpp-gl/structgl_1_1repr_1_1list__t.md): A standard Adjacency List model implemented using traditional nested containers (e.g., `std::vector>`). +- [**matrix_t**](../cpp-gl/structgl_1_1repr_1_1matrix__t.md): A standard Adjacency Matrix model implemented using traditional nested containers. ### Flat Models Contiguous 1D memory blocks that prioritize cache locality and maximum traversal speed over modification speed. -- [**flat_list_t**](../cpp-gl/structgl_1_1impl_1_1flat__list__t.md): A flattened Adjacency List model implemented using the generic [**flat_jagged_vector**](../cpp-gl/classgl_1_1flat__jagged__vector.md) data structure. -- [**flat_matrix_t**](../cpp-gl/structgl_1_1impl_1_1flat__matrix__t.md): A flattened Adjacency Matrix model implemented using the generic [**flat_matrix**](../cpp-gl/classgl_1_1flat__matrix.md) data structure. +- [**flat_list_t**](../cpp-gl/structgl_1_1repr_1_1flat__list__t.md): A flattened Adjacency List model implemented using the generic [**flat_jagged_vector**](../cpp-gl/classgl_1_1flat__jagged__vector.md) data structure. +- [**flat_matrix_t**](../cpp-gl/structgl_1_1repr_1_1flat__matrix__t.md): A flattened Adjacency Matrix model implemented using the generic [**flat_matrix**](../cpp-gl/classgl_1_1flat__matrix.md) data structure. ### Topology Support: Simple Graphs and Multigraphs @@ -204,7 +204,7 @@ Being "edge-aware" means that the internal representation stores the specific `e #### Standard Memory Models -The standard implementations utilize traditional, nested 2D containers (e.g., `std::vector>`). +The standard model implementations utilize traditional, nested 2D containers (e.g., `std::vector>`). These models are highly flexible. Because the inner containers can grow independently, they handle structural modifications, like adding vertices or edges, gracefully. The trade-off is that the memory is fragmented across the heap, which can lead to cache misses during heavy graph traversals. @@ -250,11 +250,11 @@ Depending on the chosen representation model, the computational complexity of st ### Choosing the Layout -Selecting the right `ImplTag` is a balance of your specific operational needs - use: +Selecting the right `ReprTag` is a balance of your specific operational needs - use: -- [**list_t**](../cpp-gl/structgl_1_1impl_1_1list__t.md) for highly dynamic, sparse graphs where the topology changes frequently. -- [**flat_list_t**](../cpp-gl/structgl_1_1impl_1_1flat__list__t.md) for static, sparse graphs where traversal speed and cache locality are paramount. -- [**matrix_t**](../cpp-gl/structgl_1_1impl_1_1matrix__t.md) (or [**flat_matrix_t**](../cpp-gl/structgl_1_1impl_1_1flat__matrix__t.md) if structure is entirely static) for highly dense graphs (where $\vert E \vert \approx \vert V \vert^2$) when instant $O(1)$ edge lookups are strictly required and memory footprint is not a bottleneck. +- [**list_t**](../cpp-gl/structgl_1_1repr_1_1list__t.md) for highly dynamic, sparse graphs where the topology changes frequently. +- [**flat_list_t**](../cpp-gl/structgl_1_1repr_1_1flat__list__t.md) for static, sparse graphs where traversal speed and cache locality are paramount. +- [**matrix_t**](../cpp-gl/structgl_1_1repr_1_1matrix__t.md) (or [**flat_matrix_t**](../cpp-gl/structgl_1_1repr_1_1flat__matrix__t.md) if structure is entirely static) for highly dense graphs (where $\vert E \vert \approx \vert V \vert^2$) when instant $O(1)$ edge lookups are strictly required and memory footprint is not a bottleneck. --- diff --git a/docs/gl/quick_start.md b/docs/gl/quick_start.md index e2f4c9e3..a7297f23 100644 --- a/docs/gl/quick_start.md +++ b/docs/gl/quick_start.md @@ -23,7 +23,7 @@ int main() { gl::directed_t, gl::empty_properties, gl::weight_property, - gl::impl::list_t>; + gl::repr::list_t>; gl::graph graph(5); // (3)! diff --git a/docs/hgl/algorithms/properties.md b/docs/hgl/algorithms/properties.md index b1b70f61..0caae061 100644 --- a/docs/hgl/algorithms/properties.md +++ b/docs/hgl/algorithms/properties.md @@ -5,7 +5,7 @@ Beyond hypergraph traversals, the HGL algorithms module provides a suite of ligh These algorithms are grouped into four primary categories: - [Vertex Degree Bounds](#vertex-degree-bounds): Functions for evaluating the minimum and maximum connectivity of vertices. -- [Hyperedge Size Bounds](#hyperedge-size-bounds-rank--corank): Functions for evaluating the scale of hyperedges (Rank and Corank). +- [Hyperedge Size Bounds](#hyperedge-size-bounds-rank-corank): Functions for evaluating the scale of hyperedges (Rank and Corank). - [Regularity](#regularity): Functions to check if all vertices share the same degree. - [Uniformity](#uniformity): Functions to check if all hyperedges contain the same number of vertices. diff --git a/docs/hgl/algorithms/traversal.md b/docs/hgl/algorithms/traversal.md index 77761ec5..6e85a470 100644 --- a/docs/hgl/algorithms/traversal.md +++ b/docs/hgl/algorithms/traversal.md @@ -16,8 +16,8 @@ By default, concrete traversals are designed to build a traversal tree. However, You can explicitly control this using the template's `Result` discriminator: -- [**`hgl::algorithm::ret`**](../../cpp-gl/group__HGL-Algorithm.md#enum-result_discriminator) (Default): The algorithm allocates and populates an [**hgl::algorithm::search_tree**](../../cpp-gl/group__HGL-Algorithm.md#typedef-search_tree). This structure records both the predecessor vertex and the specific hyperedge that was traversed to discover each vertex. -- [**`hgl::algorithm::noret`**](../../cpp-gl/group__HGL-Algorithm.md#enum-result_discriminator): The algorithm executes purely for side effects. The search tree allocation is completely optimized away at compile time, and the function returns `void`. +- [**`hgl::algorithm::ret`**](../../cpp-gl/group__HGL-Algorithm.md#typedef-result_discriminator) (Default): The algorithm allocates and populates an [**hgl::algorithm::search_tree**](../../cpp-gl/group__HGL-Algorithm.md#typedef-search_tree). This structure records both the predecessor vertex and the specific hyperedge that was traversed to discover each vertex. +- [**`hgl::algorithm::noret`**](../../cpp-gl/group__HGL-Algorithm.md#typedef-result_discriminator): The algorithm executes purely for side effects. The search tree allocation is completely optimized away at compile time, and the function returns `void`. ### Handling Disconnected Components diff --git a/docs/hgl/architecture.md b/docs/hgl/architecture.md index 1ac7cec2..5295cba1 100644 --- a/docs/hgl/architecture.md +++ b/docs/hgl/architecture.md @@ -35,9 +35,9 @@ The [**hgl::hypergraph**](../cpp-gl/classhgl_1_1hypergraph.md) class is the core 1. **Directionality**: Undirected vs. BF-Directed. 2. **Vertex Properties**: The data payload attached to each vertex. 3. **Hyperedge Properties**: The data payload attached to each hyperedge. -4. **Implementation Tag**: The underlying implementation model of the hypergraph. +4. **Representation Tag**: The underlying representation model of the hypergraph. - This tag dictates the data structure used for the incidence representation (e.g., Incidence List or Incidence Matrix). - - The implementation tags can be further specialized with: + - The representation tags can be further specialized with: - **Layout Tag:** The memory layout of the data structure (e.g., Bidirectional (only for list models), Vertex-Major, or Hyperedge-Major). - **Id Type:** The integral type used for internal indexing (defaults to `std::uint32_t`). @@ -45,10 +45,10 @@ To reduce boilerplate, the library provides several generic type aliases for the - Based on the directional tag: - - [**hgl::undirected_hypergraph**](../cpp-gl/group__HGL-Core.md#typedef-undirected_hypergraph) - - [**hgl::bf_directed_hypergraph**](../cpp-gl/group__HGL-Core.md#typedef-bf_directed_hypergraph) + - [**hgl::undirected_hypergraph**](../cpp-gl/group__HGL-Core.md#typedef-undirected_hypergraph) + - [**hgl::bf_directed_hypergraph**](../cpp-gl/group__HGL-Core.md#typedef-bf_directed_hypergraph) -- Based on the implementation tag: +- Based on the representation tag: - [**hgl::list_hypergraph**](../cpp-gl/group__HGL-Core.md#typedef-list_hypergraph) - [**hgl::flat_list_hypergraph**](../cpp-gl/group__HGL-Core.md#typedef-flat_list_hypergraph) @@ -200,7 +200,7 @@ for (auto in_hyperedge : hg.in_hyperedges(vertex)) { // (2)! ## Representation & Layouts -Because hypergraphs are generalizations of graphs, their topological data cannot be stored the same way as standard graphs (Adjacency Models). Instead, CPP-HGL relies on **Incidence Models** to capture the higher-order connections between vertices and hyperedges. The HGL module categorizes its memory representations via the `ImplTag` and strictly controls their memory orientation with the `LayoutTag`. +Because hypergraphs are generalizations of graphs, their topological data cannot be stored the same way as standard graphs (Adjacency Models). Instead, CPP-HGL relies on **Incidence Models** to capture the higher-order connections between vertices and hyperedges. The HGL module categorizes its memory representations via the `ReprTag` and strictly controls their memory orientation with the `LayoutTag`. ### Fundamental Representations @@ -213,9 +213,9 @@ At their core, hypergraph data structures differ in how they map vertices to the The `LayoutTag` dictates the *primary indexing dimension* of the incidence structure. Because hypergraphs map two distinctly different sets ($V$ and $E$), changing the primary index massively impacts query speeds and memory footprints: -- [**bidirectional_t**](../cpp-gl/structhgl_1_1impl_1_1bidirectional__t.md): Maintains *two* internal mappings simultaneously (Vertex-to-Hyperedges AND Hyperedge-to-Vertices). Offers optimal $O(1)$ access for both vertex degrees and hyperedge sizes, and fast iteration in both directions, at the cost of doubled memory consumption. **(Compatible only with Incidence Lists)**. -- [**hyperedge_major_t**](../cpp-gl/structhgl_1_1impl_1_1hyperedge__major__t.md): The primary index is the Hyperedge. Querying the vertices within a specific hyperedge is instantaneous, but finding which hyperedges a vertex belongs to may require an expensive full-structure scan. -- [**vertex_major_t**](../cpp-gl/structhgl_1_1impl_1_1vertex__major__t.md): The primary index is the Vertex. Querying the hyperedges connected to a specific vertex is instantaneous, but finding which vertices belong to a specific hyperedge may require an expensive, full-structure scan. +- [**bidirectional_t**](../cpp-gl/structhgl_1_1repr_1_1bidirectional__t.md): Maintains *two* internal mappings simultaneously (Vertex-to-Hyperedges AND Hyperedge-to-Vertices). Offers optimal $O(1)$ access for both vertex degrees and hyperedge sizes, and fast iteration in both directions, at the cost of doubled memory consumption. **(Compatible only with Incidence Lists)**. +- [**hyperedge_major_t**](../cpp-gl/structhgl_1_1repr_1_1hyperedge__major__t.md): The primary index is the Hyperedge. Querying the vertices within a specific hyperedge is instantaneous, but finding which hyperedges a vertex belongs to may require an expensive full-structure scan. +- [**vertex_major_t**](../cpp-gl/structhgl_1_1repr_1_1vertex__major__t.md): The primary index is the Vertex. Querying the hyperedges connected to a specific vertex is instantaneous, but finding which vertices belong to a specific hyperedge may require an expensive, full-structure scan. > [!NOTE] Matrices and Asymmetry > @@ -225,8 +225,8 @@ The `LayoutTag` dictates the *primary indexing dimension* of the incidence struc Standard models are heap-allocated, nested structures (e.g., `std::vector>`) that prioritize flexibility and dynamic structural modification. Because the inner containers can grow independently, they handle topological changes gracefully. -- [**list_t**](../cpp-gl/structhgl_1_1impl_1_1list__t.md): A standard Incidence List model implemented using traditional nested containers. -- [**matrix_t**](../cpp-gl/structhgl_1_1impl_1_1matrix__t.md): A standard Incidence Matrix model implemented using traditional nested containers. +- [**list_t**](../cpp-gl/structhgl_1_1repr_1_1list__t.md): A standard Incidence List model implemented using traditional nested containers. +- [**matrix_t**](../cpp-gl/structhgl_1_1repr_1_1matrix__t.md): A standard Incidence Matrix model implemented using traditional nested containers.
@@ -245,8 +245,8 @@ Standard models are heap-allocated, nested structures (e.g., `std::vector diff --git a/docs/hgl/quick_start.md b/docs/hgl/quick_start.md index e9b8e1b9..1c61912d 100644 --- a/docs/hgl/quick_start.md +++ b/docs/hgl/quick_start.md @@ -24,7 +24,7 @@ int main() { hgl::bf_directed_t, gl::name_property, gl::weight_property, - hgl::impl::list_t>; + hgl::repr::list_t>; hgl::hypergraph hg(4); // (3)! @@ -79,7 +79,7 @@ hyperedges: ## Understanding the Code -- **Generic Traits:** Similar to the standard GL module, the HGL module relies entirely on template abstraction. By passing a [**hgl::hypergraph_traits**](../cpp-gl/structhgl_1_1hypergraph__traits.md) struct to the [**hgl::hypergraph**](../cpp-gl/classhgl_1_1hypergraph.md) constructor, you dictate whether the hypergraph is undirected or BF-directed ([**hgl::bf_directed_t**](../cpp-gl/structhgl_1_1bf__directed__t.md)), what custom properties exist on vertices and hyperedges, and which underlying memory architecture it utilizes (e.g., [**hgl::impl::list_t**](../cpp-gl/structhgl_1_1impl_1_1list__t.md)). +- **Generic Traits:** Similar to the standard GL module, the HGL module relies entirely on template abstraction. By passing a [**hgl::hypergraph_traits**](../cpp-gl/structhgl_1_1hypergraph__traits.md) struct to the [**hgl::hypergraph**](../cpp-gl/classhgl_1_1hypergraph.md) constructor, you dictate whether the hypergraph is undirected or BF-directed ([**hgl::bf_directed_t**](../cpp-gl/structhgl_1_1bf__directed__t.md)), what custom properties exist on vertices and hyperedges, and which underlying memory architecture it utilizes (e.g., [**hgl::repr::list_t**](../cpp-gl/structhgl_1_1repr_1_1list__t.md)). - **Generalized Incidence:** Unlike standard graphs where an edge connects exactly two vertices, hyperedges connect sets of vertices of arbitrary sizes. In a BF-directed hypergraph, `add_hyperedge` accepts an iterable range of *tail* (source) vertices and *head* (destination) vertices and represents a single connection from all tail vertices to all head vertices simultaneously. diff --git a/docs/index.md b/docs/index.md index e4559b25..2c8cc634 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,8 +12,14 @@ [![G++](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml) [![Clang++](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml) + +
+ +
+ [![Code Formatting](https://github.com/SpectraL519/cpp-gl/actions/workflows/format.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/format.yaml) [![Benchmarks Smoke Test](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/benchmarks.yaml) +[![changelog](https://img.shields.io/badge/changelog-blue.svg?logo=github)](https://github.com/SpectraL519/cpp-gl/releases)
@@ -31,17 +37,34 @@ Designed strictly around modern C++ paradigms, the library heavily leverages tem To accommodate different mathematical models without compromising API clarity or performance, the library is strictly partitioned into two primary modules: -- **GL (Graph Library):** The core module dedicated to standard graphs. It handles both directed and undirected topologies where edges represent connections between two vertices. It provides a comprehensive suite of utilities including structural generators, graph modifiers, and a broad spectrum of classical graph algorithms. -- **HGL (Hypergraph Library):** A specialized module dedicated to hypergraphs, where a single hyperedge represent higher-order connections. It features generalized traversal algorithms and incidence-based memory models tailored for complex, multi-way relationships. +- **GL (Graph Library):** The core module dedicated to standard graphs. It handles both directed and undirected topologies where edges represent connections between exactly two vertices. It provides a comprehensive suite of utilities including structural generators, graph modifiers, and a broad spectrum of classical graph algorithms. +- **HGL (Hypergraph Library):** A specialized module dedicated to hypergraphs, where a single hyperedge represents a higher-order connection between an arbitrary number of vertices. It features generalized traversal algorithms and incidence-based memory models tailored for complex, multi-way relationships. + +--- + +## Core Features + +Because both modules share the same fundamental design philosophy, they offer a unified, symmetrical feature set tailored to their respective mathematical domains: -## GL: Core Features +- **Shared Zero-Cost Infrastructure:** By relying on C++20 concepts instead of virtual interfaces and dynamic dispatch, CPP-GL eliminates vtable overhead while enforcing strict compile-time contracts. Crucially, the **HGL module is built strictly on top of the GL module**, directly reusing its core infrastructure (ID types, traits, memory structures) to ensure maximum code reuse, while allowing the GL module to remain completely standalone for standard graph use cases. +- **Unified Topology APIs:** The `gl::graph` and `hgl::hypergraph` classes offer consistent interfaces that completely abstract away the underlying memory models. Users can seamlessly swap between different backend representations without rewriting their traversal logic, property accesses, or algorithm calls. +- **Flexible Memory Layouts:** The library provides a comprehensive suite of memory-efficient representations. Users can choose between dynamic container-based layouts (Lists and Matrices) and highly optimized, cache-friendly contiguous array structures (Flat Lists and Flat Matrices). The HGL module further extends this by allowing users to specify the orientation of the memory models to optimize generalized incidence queries. +- **Customizable Element Properties:** Vertices, edges, and hyperedges can carry arbitrary, user-defined payloads. Whether you are assigning standard metric weights and colors or attaching complex, application-specific data structures, the library's traits system ensures that property injection and access remain strictly type-safe and performant. +- **Dual-Layered Algorithmic Architecture:** CPP-GL cleanly separates traversal mechanics from specific problem-solving logic. At the foundation, highly generic search engines (like BFS and DFS) empower users to construct completely custom algorithms via injected callbacks. Layered seamlessly above this is a comprehensive suite of ready-to-use concrete algorithms, ranging from standard graph pathfinding to specialized hypergraph reachability (such as B-Searches and F-Searches). +- **Robust I/O Facilities:** Native serialization and formatting tools make it simple to pipe topologies directly to and from standard C++ streams and files. Both the GL and HGL modules share a unified set of stream options for visual output, while relying on dedicated, easily parsable flat-text formats (GSF and HGSF) to ensure fast and predictable data serialization. -- **Unified API:** The `gl::graph` class offers a single, consistent interface that completely abstracts away the underlying data structures. Users can seamlessly swap between different backend representations without needing to rewrite any of their traversal logic, property accesses, or algorithm calls. -- **Flexible Memory Layouts:** The library provides a comprehensive suite of memory-efficient representations tailored to different graph types and access patterns. Users can choose between standard container-based layouts (Adjacency Lists and Matrices) and highly optimized, cache-friendly contiguous array structures (Flat Lists and Flat Matrices). -- **Customizable Element Properties:** Vertices and edges can carry arbitrary, user-defined payloads. Whether you are assigning standard metric weights and colors or attaching complex, application-specific data structures, the library's traits system ensures that property injection and access remain strictly type-safe and performant. -- **Zero-Cost Abstractions:** By relying on C++20 concepts instead of virtual interfaces and dynamic dispatch, CPP-GL eliminates vtable overhead while enforcing strict compile-time contracts. -- **Extensible Engines & Concrete Algorithms:** CPP-GL features a dual-layered algorithmic architecture. At its core, it provides highly generic search templates (such as BFS, DFS and Priority-First Search) that act as foundational engines, allowing users to build entirely new algorithms by injecting custom callbacks. Built upon these engines is a robust suite of concrete, ready-to-use algorithms for immediate application. -- **Robust I/O Facilities:** Built-in serialization and formatting tools allow for seamless translation of in-memory graphs to and from standard streams and files, utilizing a shared global state for consistent formatting. +--- + +## Compiler support + +| Compiler | Min version | +| :-: | :-: | +| GNU G++ | 14 | +| Clang | 18 | + +> [!NOTE] C++23 Support +> +> Although currently the project has been properly verified using only the G++ and Clang compilers it should work fine with other compilers with C++23 support like MSVC. --- @@ -61,8 +84,8 @@ include(FetchContent) FetchContent_Declare( cpp-gl - GIT_REPOSITORY [https://github.com/SpectraL519/cpp-gl.git](https://github.com/SpectraL519/cpp-gl.git) - GIT_TAG # Spcify the desired version tag, branch, or specific commit + GIT_REPOSITORY https://github.com/SpectraL519/cpp-gl.git + GIT_TAG # (1)! ) FetchContent_MakeAvailable(cpp-gl) @@ -70,25 +93,17 @@ FetchContent_MakeAvailable(cpp-gl) add_executable(my_project main.cpp) set_target_properties(my_project PROPERTIES - CXX_STANDARD 23 # (1)! + CXX_STANDARD 23 # (2)! CXX_STANDARD_REQUIRED YES ) target_link_libraries(my_project PRIVATE cpp-gl) ``` -1. The CPP-GL library requires C++23 - -### Option B: CMake `find_package` - -If you have already downloaded or installed the library locally, you can add the /include path to your system and link it using `find_package`: - -```cmake -find_package(cpp-gl REQUIRED) -target_link_libraries(my_project PRIVATE cpp-gl::cpp-gl) -``` +1. Specify the desired version tag, branch, or specific commit +2. The CPP-GL library requires C++23 -### Option C: Including the Headers Directly +### Option B: Including the Headers Directly If you do not wish to use CMake, you can simply download the desired version of the library from the [Releases Page](https://github.com/SpectraL519/cpp-gl/releases) and add the `include` directory of the library to your project via the `-I/include` flag. @@ -99,4 +114,4 @@ If you do not wish to use CMake, you can simply download the desired version of Ready to write some code? Choose a module below to view its Quick Start guide and dive into the tutorials: * [**Get Started with GL (Standard Graphs)**](gl/quick_start.md) - Master the core concepts, build custom topologies, and explore the robust suite of generic traversal engines and classical algorithms. -* **Get Started with HGL (Hypergraphs)** - *(Coming Soon)* +* [**Get Started with HGL (Hypergraphs)**](hgl/quick_start.md) - Master generalized incidence, configure complex memory layouts, and evaluate higher-order reachability across hypergraph networks. diff --git a/include/gl/algorithm/core.hpp b/include/gl/algorithm/core.hpp index cec2293d..731505fc 100644 --- a/include/gl/algorithm/core.hpp +++ b/include/gl/algorithm/core.hpp @@ -18,7 +18,7 @@ namespace gl::algorithm { // --- general types --- -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief A tag type used to explicitly indicate the absence of a callback function. /// /// > [!NOTE] Performance vs. Empty Lambdas @@ -30,7 +30,7 @@ namespace gl::algorithm { /// > and speeds up compilation times. struct empty_callback {}; -/// @ingroup GL GL-Algorithm GL-Types +/// @ingroup GL-Algorithm GL-Types /// @brief Represents a generic tri-state decision for control flow. /// /// Used by custom predicates to determine how to proceed with a given item, execution step, or operation. @@ -78,7 +78,7 @@ struct decision { eval value; }; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Tag used to statically dictate whether an algorithm should return a constructed result or execute purely for side effects. /// /// > [!NOTE] Namespace Availability @@ -96,7 +96,7 @@ enum class result_discriminator : bool { }; using enum result_discriminator; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Resolves to the specified `ResultType` if `Result` is `ret`, otherwise resolves to `void`. /// /// ### See Also @@ -105,7 +105,7 @@ using enum result_discriminator; template using result_type = std::conditional_t; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Resolves to the specified `ResultType` if `Result` is `ret`, otherwise resolves to `std::monostate`. /// /// Useful for returning dummy values from conditionally compiled algorithm branches. @@ -119,13 +119,13 @@ using non_void_result_type = // --- traversal types --- -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Maps a vertex ID to its predecessor's ID in a traversal tree. /// @tparam GraphType The type of the graph being traversed. template using predecessors_map = std::vector; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Represents an active node in a search container (e.g., a BFS queue or DFS stack). /// @tparam GraphType The type of the graph being searched. template @@ -155,7 +155,7 @@ struct search_node { // --- constants --- -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Constant representing the absence of a root vertex ID for a specific ID type. /// /// ### See Also @@ -165,7 +165,7 @@ struct search_node { template inline constexpr IdType no_root_v = invalid_id_v; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Tag type providing an implicit conversion to the appropriate `no_root_v` for any numeric ID type. /// /// ### See Also @@ -185,7 +185,7 @@ struct no_root_t { } }; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Global constant representing the absence of a root vertex. /// /// ### See Also diff --git a/include/gl/algorithm/pathfinding/dijkstra.hpp b/include/gl/algorithm/pathfinding/dijkstra.hpp index b8414715..f811aacb 100644 --- a/include/gl/algorithm/pathfinding/dijkstra.hpp +++ b/include/gl/algorithm/pathfinding/dijkstra.hpp @@ -15,7 +15,7 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief A descriptor structure holding the results of a single-source shortest path execution. /// /// ### Template Parameters @@ -39,13 +39,13 @@ struct paths_descriptor { std::vector distances; }; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief An alias for @ref gl::algorithm::paths_descriptor "paths_descriptor" that automatically deduces the appropriate distance type for the graph. /// @tparam G The type of the graph. template using paths_descriptor_type = paths_descriptor>; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Factory function to create an initialized paths descriptor sized for the given graph. /// @tparam G The type of the graph. /// @param graph The graph to size the descriptor against. @@ -55,7 +55,7 @@ template return paths_descriptor_type{graph.n_vertices()}; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Internal node structure for Dijkstra's algorithm to snapshot distances and preserve heap invariants. /// /// This structure is used in the @ref gl::algorithm::dijkstra_shortest_paths "dijkstra_shortest_paths" algorithm @@ -74,7 +74,7 @@ struct dijkstra_search_node { distance; ///< The accumulated distance from the source to this vertex at the time of enqueueing. }; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Computes the shortest paths from a single source vertex to all reachable vertices using Dijkstra's algorithm. /// /// This algorithm utilizes the generic @ref gl::algorithm::pfs "pfs" template using the dedicated @@ -105,9 +105,9 @@ struct dijkstra_search_node { /// > /// > The time complexity depends on the underlying representation of `GraphType` and the priority queue overhead: /// > - **Adjacency List Representations**: \f$O((|V| + |E|) \log |V|)\f$ -/// > - *Includes:* @ref gl::impl::list_t "list_t" and @ref gl::impl::flat_list_t "flat_list_t". +/// > - *Includes:* @ref gl::repr::list_t "list_t" and @ref gl::repr::flat_list_t "flat_list_t". /// > - **Adjacency Matrix Representations**: \f$O(|V|^2 + |E| \log |V|)\f$ -/// > - *Includes:* @ref gl::impl::matrix_t "matrix_t" and @ref gl::impl::flat_matrix_t "flat_matrix_t". +/// > - *Includes:* @ref gl::repr::matrix_t "matrix_t" and @ref gl::repr::flat_matrix_t "flat_matrix_t". /// > - *Note:* Iterating over adjacent vertices requires scanning the entire \f$|V|\f$-length matrix row. /// /// ### Template Parameters @@ -203,7 +203,7 @@ template < return paths; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Reconstructs the sequence of vertices forming a path to a specific target. /// /// This utility walks backward through a predecessor map, starting from the `vertex_id` diff --git a/include/gl/algorithm/spanning_tree/prim_mst.hpp b/include/gl/algorithm/spanning_tree/prim_mst.hpp index 46f34677..c234c98a 100644 --- a/include/gl/algorithm/spanning_tree/prim_mst.hpp +++ b/include/gl/algorithm/spanning_tree/prim_mst.hpp @@ -15,7 +15,7 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief A descriptor structure holding the results of a Minimum Spanning Tree (MST) execution. /// /// @tparam G The type of the undirected graph. Must satisfy the [**c_undirected_graph**](gl_concepts.md#gl-traits-c-undirected-graph) concept. @@ -40,7 +40,7 @@ struct mst_descriptor { weight_type weight = static_cast(0); }; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Computes the Minimum Spanning Tree (MST) of an undirected graph using Prim's algorithm with an edge-based priority queue. /// /// This implementation uses a standard binary heap (`std::priority_queue`) to store and sort edges based on their weight. @@ -59,10 +59,10 @@ struct mst_descriptor { /// > /// > The time complexity depends on the underlying representation of `GraphType` and the queue overhead: /// > - **Adjacency List Representations**: \f$O(|E| \log |E|)\f$ -/// > - *Includes:* @ref gl::impl::list_t "list_t" and @ref gl::impl::flat_list_t "flat_list_t". +/// > - *Includes:* @ref gl::repr::list_t "list_t" and @ref gl::repr::flat_list_t "flat_list_t". /// > - *Note:* In simple graphs, this simplifies to \f$O(|E| \log |V|)\f$. However, because list models allow multigraphs, the queue size and operations scale strictly with \f$|E|\f$. /// > - **Adjacency Matrix Representations**: \f$O(|V|^2 + |E| \log |V|)\f$ -/// > - *Includes:* @ref gl::impl::matrix_t "matrix_t" and @ref gl::impl::flat_matrix_t "flat_matrix_t". +/// > - *Includes:* @ref gl::repr::matrix_t "matrix_t" and @ref gl::repr::flat_matrix_t "flat_matrix_t". /// > - *Note:* Iterating over incident edges requires scanning the entire \f$|V|\f$-length matrix row. Since matrices represent simple graphs, the heap operations safely simplify to \f$O(\log |V|)\f$. /// /// ### Template Parameters @@ -133,7 +133,7 @@ template return mst; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Computes the Minimum Spanning Tree (MST) of an undirected graph using Prim's algorithm with a vertex-based array heap. /// /// This variation maintains a heap of vertex IDs based on their minimum known connection cost. diff --git a/include/gl/algorithm/templates/bfs.hpp b/include/gl/algorithm/templates/bfs.hpp index a87e8b83..9e91c4fb 100644 --- a/include/gl/algorithm/templates/bfs.hpp +++ b/include/gl/algorithm/templates/bfs.hpp @@ -15,7 +15,7 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief A highly customizable, generic Breadth-First Search (BFS) algorithm engine. /// /// This template does not implement a specific algorithm (like finding a shortest path). diff --git a/include/gl/algorithm/templates/dfs.hpp b/include/gl/algorithm/templates/dfs.hpp index b9bf8db2..3a659157 100644 --- a/include/gl/algorithm/templates/dfs.hpp +++ b/include/gl/algorithm/templates/dfs.hpp @@ -15,7 +15,7 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief A highly customizable, generic iterative Depth-First Search (DFS) algorithm engine. /// /// This engine provides the strict structural execution of a stack-based Depth-First Search. @@ -130,7 +130,7 @@ bool dfs( return true; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief A highly customizable, generic recursive Depth-First Search (DFS) algorithm engine. /// /// This engine mirrors the iterative `dfs` behavior but utilizes the C++ call stack. diff --git a/include/gl/algorithm/templates/pfs.hpp b/include/gl/algorithm/templates/pfs.hpp index 717befab..b44b5956 100644 --- a/include/gl/algorithm/templates/pfs.hpp +++ b/include/gl/algorithm/templates/pfs.hpp @@ -17,7 +17,7 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief A highly customizable, generic Priority-First Search (PFS) algorithm engine. /// /// This template provides the strict structural execution of a priority queue-based search. diff --git a/include/gl/algorithm/topology/coloring.hpp b/include/gl/algorithm/topology/coloring.hpp index fbc5fb1d..644c5592 100644 --- a/include/gl/algorithm/topology/coloring.hpp +++ b/include/gl/algorithm/topology/coloring.hpp @@ -12,11 +12,11 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Alias for a container mapping vertex indices to their calculated binary (bipartite) colors. using bicoloring_type = std::vector; -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Attempts to compute a valid bipartite (2-color) coloring for the given graph. /// /// This algorithm utilizes the generic @ref gl::algorithm::bfs "bfs" template to traverse the graph and @@ -40,9 +40,9 @@ using bicoloring_type = std::vector; /// > /// > The time complexity depends entirely on the underlying representation of `GraphType`: /// > - **Adjacency List Representations**: \f$O(|V| + |E|)\f$ -/// > - *Includes:* @ref gl::impl::list_t "list_t" and @ref gl::impl::flat_list_t "flat_list_t". +/// > - *Includes:* @ref gl::repr::list_t "list_t" and @ref gl::repr::flat_list_t "flat_list_t". /// > - **Adjacency Matrix Representations**: \f$O(|V|^2)\f$ -/// > - *Includes:* @ref gl::impl::matrix_t "matrix_t" and @ref gl::impl::flat_matrix_t "flat_matrix_t". +/// > - *Includes:* @ref gl::repr::matrix_t "matrix_t" and @ref gl::repr::flat_matrix_t "flat_matrix_t". /// > - *Note:* Iterating over adjacent vertices requires scanning the entire \f$|V|\f$-length matrix row. /// /// ### Template Parameters @@ -113,7 +113,7 @@ template < return coloring; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Convenience wrapper for the @ref gl::algorithm::bipartite_coloring "bipartite_coloring" algorithm to check if a graph is bipartite without extracting the exact coloring map. /// @param graph The graph to evaluate. /// @return `true` if the graph is bipartite (2-colorable), `false` otherwise. @@ -123,7 +123,7 @@ template < return bipartite_coloring(graph).has_value(); } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Applies a computed range of binary colors to the property payload of each vertex in the graph. /// /// ### Template Parameters diff --git a/include/gl/algorithm/topology/topological_sort.hpp b/include/gl/algorithm/topology/topological_sort.hpp index 25b76e4b..1134631d 100644 --- a/include/gl/algorithm/topology/topological_sort.hpp +++ b/include/gl/algorithm/topology/topological_sort.hpp @@ -12,7 +12,7 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Computes a topological ordering of the vertices in a Directed Acyclic Graph (DAG). /// /// This implementation relies on Kahn's Algorithm. It utilizes the generic @ref gl::algorithm::bfs "bfs" @@ -42,9 +42,9 @@ namespace gl::algorithm { /// > /// > The time complexity depends entirely on the underlying representation of `GraphType`: /// > - **Adjacency List Representations**: \f$O(|V| + |E|)\f$ -/// > - *Includes:* @ref gl::impl::list_t "list_t" and @ref gl::impl::flat_list_t "flat_list_t". +/// > - *Includes:* @ref gl::repr::list_t "list_t" and @ref gl::repr::flat_list_t "flat_list_t". /// > - **Adjacency Matrix Representations**: \f$O(|V|^2)\f$ -/// > - *Includes:* @ref gl::impl::matrix_t "matrix_t" and @ref gl::impl::flat_matrix_t "flat_matrix_t". +/// > - *Includes:* @ref gl::repr::matrix_t "matrix_t" and @ref gl::repr::flat_matrix_t "flat_matrix_t". /// > - *Note:* Iterating over adjacent vertices requires scanning the entire \f$|V|\f$-length matrix row. /// /// ### Template Parameters diff --git a/include/gl/algorithm/traits.hpp b/include/gl/algorithm/traits.hpp index 5e841cbe..866c467b 100644 --- a/include/gl/algorithm/traits.hpp +++ b/include/gl/algorithm/traits.hpp @@ -13,12 +13,12 @@ namespace gl::traits { -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept checking if a given type is the @ref gl::algorithm::empty_callback "empty_callback" tag. template concept c_empty_callback = std::same_as; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept checking if a type is callable with specific arguments and returns a specific type. /// @tparam F The callable type. /// @tparam ReturnType The expected return type. @@ -26,27 +26,27 @@ concept c_empty_callback = std::same_as; template concept c_callback = std::is_invocable_r_v; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept allowing either a valid callback or the explicit absence of one through the use of @ref gl::algorithm::empty_callback "empty_callback". template concept c_optional_callback = c_empty_callback or c_callback; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept checking if a type is a boolean predicate callable with specific arguments. template concept c_predicate = std::predicate; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept allowing either a valid boolean predicate or the explicit absence of one through the use of @ref gl::algorithm::empty_callback "empty_callback". template concept c_optional_predicate = c_empty_callback or c_predicate; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept checking if a type is a predicate returning a @ref gl::algorithm::decision "decision". template concept c_decision_predicate = std::is_invocable_r_v; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept allowing either a valid decision predicate or the explicit absence of one. template concept c_optional_decision_predicate = c_empty_callback or c_decision_predicate; diff --git a/include/gl/algorithm/traversal/breadth_first_search.hpp b/include/gl/algorithm/traversal/breadth_first_search.hpp index 8897a8a9..6ab6fc2d 100644 --- a/include/gl/algorithm/traversal/breadth_first_search.hpp +++ b/include/gl/algorithm/traversal/breadth_first_search.hpp @@ -14,7 +14,7 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Executes a concrete Breadth-First Search (BFS) traversal over the graph. /// /// This function utilizes the generic @ref gl::algorithm::bfs "bfs" template to perform a standard queue-based traversal. @@ -48,9 +48,9 @@ namespace gl::algorithm { /// > /// > The time complexity depends entirely on the underlying representation of `GraphType`: /// > - **Adjacency List Representations**: \f$O(|V| + |E|)\f$ -/// > - *Includes:* @ref gl::impl::list_t "list_t" and @ref gl::impl::flat_list_t "flat_list_t". +/// > - *Includes:* @ref gl::repr::list_t "list_t" and @ref gl::repr::flat_list_t "flat_list_t". /// > - **Adjacency Matrix Representations**: \f$O(|V|^2)\f$ -/// > - *Includes:* @ref gl::impl::matrix_t "matrix_t" and @ref gl::impl::flat_matrix_t "flat_matrix_t". +/// > - *Includes:* @ref gl::repr::matrix_t "matrix_t" and @ref gl::repr::flat_matrix_t "flat_matrix_t". /// > - *Note:* Iterating over adjacent vertices requires scanning the entire \f$|V|\f$-length matrix row. /// /// ### Template Parameters diff --git a/include/gl/algorithm/traversal/depth_first_search.hpp b/include/gl/algorithm/traversal/depth_first_search.hpp index 2a8571e7..cd05c937 100644 --- a/include/gl/algorithm/traversal/depth_first_search.hpp +++ b/include/gl/algorithm/traversal/depth_first_search.hpp @@ -14,7 +14,7 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Executes a concrete iterative Depth-First Search (DFS) traversal over the graph. /// /// This function utilizes the generic @ref gl::algorithm::dfs "dfs" template to perform a standard, stack-based traversal. @@ -56,9 +56,9 @@ namespace gl::algorithm { /// > /// > The time complexity depends entirely on the underlying representation of `GraphType`: /// > - **Adjacency List Representations**: \f$O(|V| + |E|)\f$ -/// > - *Includes:* @ref gl::impl::list_t "list_t" and @ref gl::impl::flat_list_t "flat_list_t". +/// > - *Includes:* @ref gl::repr::list_t "list_t" and @ref gl::repr::flat_list_t "flat_list_t". /// > - **Adjacency Matrix Representations**: \f$O(|V|^2)\f$ -/// > - *Includes:* @ref gl::impl::matrix_t "matrix_t" and @ref gl::impl::flat_matrix_t "flat_matrix_t". +/// > - *Includes:* @ref gl::repr::matrix_t "matrix_t" and @ref gl::repr::flat_matrix_t "flat_matrix_t". /// > - *Note:* Iterating over adjacent vertices requires scanning the entire \f$|V|\f$-length matrix row. /// /// ### Template Parameters @@ -123,7 +123,7 @@ result_type> depth_first_search( return pred_map; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Executes a concrete recursive Depth-First Search (DFS) traversal over the graph. /// /// This function relies on the generic @ref gl::algorithm::r_dfs "r_dfs" template. Instead of a @@ -156,9 +156,9 @@ result_type> depth_first_search( /// > /// > The time complexity depends entirely on the underlying representation of `GraphType`: /// > - **Adjacency List Representations**: \f$O(|V| + |E|)\f$ -/// > - *Includes:* @ref gl::impl::list_t "list_t" and @ref gl::impl::flat_list_t "flat_list_t". +/// > - *Includes:* @ref gl::repr::list_t "list_t" and @ref gl::repr::flat_list_t "flat_list_t". /// > - **Adjacency Matrix Representations**: \f$O(|V|^2)\f$ -/// > - *Includes:* @ref gl::impl::matrix_t "matrix_t" and @ref gl::impl::flat_matrix_t "flat_matrix_t". +/// > - *Includes:* @ref gl::repr::matrix_t "matrix_t" and @ref gl::repr::flat_matrix_t "flat_matrix_t". /// > - *Note:* Iterating over adjacent vertices requires scanning the entire \f$|V|\f$-length matrix row. /// /// ### Template Parameters diff --git a/include/gl/algorithm/util.hpp b/include/gl/algorithm/util.hpp index cd22042d..b7bfde13 100644 --- a/include/gl/algorithm/util.hpp +++ b/include/gl/algorithm/util.hpp @@ -14,7 +14,7 @@ namespace gl::algorithm { -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Initializes a predecessor map based on the static result discriminator. /// @tparam Result The compilation tag determining if the map should actually be built. /// @tparam G The type of the graph. @@ -30,7 +30,7 @@ init_predecessors_map(const G& graph) { return return_t(); } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Checks if a specific vertex was reached during a traversal. /// @tparam IdType The integral type of the vertex ID. /// @param pred_map The predecessor map populated by the traversal. @@ -44,7 +44,7 @@ template return pred_map[to_idx(vertex_id)] != invalid_id; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Initializes a search container with the starting root vertex. /// @tparam G The type of the graph. /// @tparam InitRangeType The underlying container type for the container. @@ -58,7 +58,7 @@ template < return InitRangeType{search_node{root_vertex_id}}; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Generates a default lambda predicate that checks if a vertex has not yet been visited. /// @param visited A reference to the boolean array tracking visited vertices. /// @return A callable predicate evaluating to `true` if the vertex is unvisited. @@ -66,7 +66,7 @@ template < return [&](traits::c_id_type auto vertex_id) -> bool { return not visited[to_idx(vertex_id)]; }; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Generates a default lambda callback that marks a vertex as visited and updates the predecessor map. /// @tparam G The type of the graph. /// @tparam Result The static discriminator indicating if the predecessor map should be updated. @@ -88,7 +88,7 @@ template }; } -/// @ingroup GL GL-Algorithm +/// @ingroup GL-Algorithm /// @brief Generates a default lambda predicate that checks if a node corresponding to an adjacent vertex should be enqueued into the search container. /// @tparam G The type of the graph. /// @tparam AsDecision If `true`, the generated predicate returns a @ref gl::algorithm::decision "decision" instead of a raw boolean. diff --git a/include/gl/constants.hpp b/include/gl/constants.hpp index e0412216..0d9b07dc 100644 --- a/include/gl/constants.hpp +++ b/include/gl/constants.hpp @@ -13,7 +13,7 @@ namespace gl { -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief A constant representing the initial ID value of 0 for graph elements. /// @tparam IdType The type of the ID, which must satisfy the [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) concept. /// ### See Also @@ -23,7 +23,7 @@ namespace gl { template inline constexpr IdType initial_id_v{0}; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief A helper type that can be implicitly converted to the initial ID value of 0 for any valid ID type. /// ### See Also /// - [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) @@ -37,7 +37,7 @@ struct initial_id_t { } }; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief An `initial_id_t` tag constant that can be used to represent the initial ID value of 0 for graph elements in a type-safe manner. /// /// ### Example Usage @@ -56,7 +56,7 @@ inline constexpr initial_id_t initial_id{}; // --- invalid id --- -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief A constant representing the invalid ID value for graph elements, defined as the maximum value of the specified ID type. /// @tparam IdType The type of the ID, which must satisfy the [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) concept. /// ### See Also @@ -66,7 +66,7 @@ inline constexpr initial_id_t initial_id{}; template inline constexpr IdType invalid_id_v{std::numeric_limits::max()}; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief A helper type that can be implicitly converted to the invalid ID value for any valid ID type. /// ### See Also /// - [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) @@ -95,7 +95,7 @@ struct invalid_id_t { } }; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief An `invalid_id_t` tag constant that can be used to represent the invalid ID value for graph elements in a type-safe manner. /// /// ### Example Usage diff --git a/include/gl/conversion.hpp b/include/gl/conversion.hpp index a2e9e85e..c27fdeb8 100644 --- a/include/gl/conversion.hpp +++ b/include/gl/conversion.hpp @@ -7,9 +7,9 @@ #pragma once -#include "gl/decl/impl_tags.hpp" +#include "gl/decl/repr_tags.hpp" #include "gl/graph.hpp" -#include "gl/impl/impl_tags.hpp" +#include "gl/repr_tags.hpp" #include "gl/traits.hpp" #include "gl/types/core.hpp" @@ -19,53 +19,53 @@ namespace gl { namespace traits { -/// @ingroup GL GL-Traits -/// @brief Utility trait type used to swap the implementation tag of a graph traits or graph type. +/// @ingroup GL-Traits +/// @brief Utility trait type used to swap the representation tag of a graph traits or graph type. /// ### See Also: -/// - @ref gl::to "to" : For the function that utilizes this trait to perform graph conversions between different implementations. -template +/// - @ref gl::to "to" : For the function that utilizes this trait to perform graph conversions between different representations. +template requires c_graph or c_instantiation_of -struct swap_impl_tag; +struct swap_repr_tag; -/// @ingroup GL GL-Traits -/// @brief Specialization of @ref gl::traits::swap_impl_tag "swap_impl_tag" for the @ref gl::graph_traits "graph_traits" type. +/// @ingroup GL-Traits +/// @brief Specialization of @ref gl::traits::swap_repr_tag "swap_repr_tag" for the @ref gl::graph_traits "graph_traits" type. template < traits::c_graph_directional_tag Dir, traits::c_properties VP, traits::c_properties EP, - traits::c_graph_impl_tag OldImplTag, - traits::c_graph_impl_tag NewImplTag, + traits::c_graph_repr_tag OldImplTag, + traits::c_graph_repr_tag NewImplTag, traits::c_id_type IdType> -struct swap_impl_tag, NewImplTag> { +struct swap_repr_tag, NewImplTag> { using type = graph_traits; }; -/// @ingroup GL GL-Traits -/// @brief Specialization of @ref gl::traits::swap_impl_tag "swap_impl_tag" for the @ref gl::graph "graph" class. +/// @ingroup GL-Traits +/// @brief Specialization of @ref gl::traits::swap_repr_tag "swap_repr_tag" for the @ref gl::graph "graph" class. template < traits::c_graph_directional_tag Dir, traits::c_properties VP, traits::c_properties EP, - traits::c_graph_impl_tag OldImplTag, - traits::c_graph_impl_tag NewImplTag, + traits::c_graph_repr_tag OldImplTag, + traits::c_graph_repr_tag NewImplTag, traits::c_id_type IdType> -struct swap_impl_tag>, NewImplTag> { +struct swap_repr_tag>, NewImplTag> { using type = graph>; }; -/// @ingroup GL GL-Traits -/// @brief Alias template for easier usage of the @ref gl::traits::swap_impl_tag "swap_impl_tag" trait to resolve the swapped type directly. +/// @ingroup GL-Traits +/// @brief Alias template for easier usage of the @ref gl::traits::swap_repr_tag "swap_repr_tag" trait to resolve the swapped type directly. /// ### See Also: -/// - @ref gl::to "to" : For the function that utilizes this trait to perform graph conversions between different implementations. -template +/// - @ref gl::to "to" : For the function that utilizes this trait to perform graph conversions between different representations. +template requires c_graph or c_instantiation_of -using swap_impl_tag_t = typename swap_impl_tag::type; +using swap_repr_tag_t = typename swap_repr_tag::type; } // namespace traits namespace detail { -template +template struct to_impl { template static void convert(TargetGraph& target, SourceGraph& source) { @@ -84,8 +84,8 @@ struct to_impl { }; // Conversion: identity -template -struct to_impl { +template +struct to_impl { template static void convert(TargetGraph& target, SourceGraph& source) { target._impl = std::move(source._impl); @@ -94,7 +94,7 @@ struct to_impl { // Conversion: list -> flat list template <> -struct to_impl { +struct to_impl { template static void convert(TargetGraph& target, SourceGraph& source) { auto& target_list = target._impl._list; @@ -114,7 +114,7 @@ struct to_impl { // Conversion: flat list -> list template <> -struct to_impl { +struct to_impl { template static void convert(TargetGraph& target, SourceGraph& source) { auto& target_list = target._impl._list; @@ -128,7 +128,7 @@ struct to_impl { // Conversion: matrix -> flat matrix template <> -struct to_impl { +struct to_impl { template static void convert(TargetGraph& target, SourceGraph& source) { auto& target_matrix = target._impl._matrix; @@ -145,7 +145,7 @@ struct to_impl { // Conversion: flat matrix -> matrix template <> -struct to_impl { +struct to_impl { template static void convert(TargetGraph& target, SourceGraph& source) { auto& target_matrix = target._impl._matrix; @@ -159,29 +159,29 @@ struct to_impl { } // namespace detail -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @headerfile gl/conversion.hpp -/// @brief Converts a graph from one implementation model to another. +/// @brief Converts a graph from one representation model to another. /// /// This function efficiently transforms a graph's underlying memory representation (e.g., from a standard adjacency list to a flattened adjacency list) while preserving its exact topology, properties, and identifiers. /// /// ### Template Parameters /// | Parameter | Description | Constraints | /// | :------------ | :---------- | :---------- | -/// | TargetImplTag | The implementation tag of the desired target representation (e.g., `gl::impl::flat_list_t`) | [**c_graph_impl_tag**](gl_concepts.md#gl-traits-c-graph-impl-tag) | +/// | TargetImplTag | The representation tag of the desired target representation (e.g., `gl::repr::flat_list_t`) | [**c_graph_repr_tag**](gl_concepts.md#gl-traits-c-graph-repr-tag) | /// | Graph | The type of the source graph, which will be automatically deduced from the function argument. | [**c_graph**](gl_concepts.md#gl-traits-c-graph) | /// /// @param source The graph to convert. After the operation it will be left in a valid, empty state. /// @return A new graph containing the moved data, structured according to `TargetImplTag`. /// /// ### See Also -/// - @ref gl::traits::swap_impl_tag "swap_impl_tag" : For the trait used to resolve the target graph type with the swapped implementation tag. -template +/// - @ref gl::traits::swap_repr_tag "swap_repr_tag" : For the trait used to resolve the target graph type with the swapped representation tag. +template [[nodiscard]] auto to(Graph&& source) { using source_traits = typename Graph::traits_type; - using source_impl_tag = typename source_traits::implementation_tag; + using source_impl_tag = typename source_traits::representation_tag; - using target_traits = traits::swap_impl_tag_t; + using target_traits = traits::swap_repr_tag_t; using target_graph = graph; target_graph target; diff --git a/include/gl/decl/graph_traits.hpp b/include/gl/decl/graph_traits.hpp index 9367e609..bde26719 100644 --- a/include/gl/decl/graph_traits.hpp +++ b/include/gl/decl/graph_traits.hpp @@ -4,7 +4,7 @@ #pragma once -#include "gl/decl/impl_tags.hpp" +#include "gl/decl/repr_tags.hpp" #include "gl/directional_tags.hpp" #include "gl/traits.hpp" @@ -14,7 +14,7 @@ template < traits::c_graph_directional_tag DirectionalTag, traits::c_properties VertexProperties, traits::c_properties EdgeProperties, - traits::c_graph_impl_tag ImplTag, + traits::c_graph_repr_tag ReprTag, traits::c_id_type IdType> struct graph_traits; diff --git a/include/gl/decl/impl_tags.hpp b/include/gl/decl/impl_tags.hpp deleted file mode 100644 index 02844ce9..00000000 --- a/include/gl/decl/impl_tags.hpp +++ /dev/null @@ -1,47 +0,0 @@ -// Copyright (c) 2024-2026 Jakub Musiał -// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl). -// Licensed under the MIT License. See the LICENSE file in the project root for full license information. - -/// @file gl/decl/impl_tags.hpp -/// @brief Forward declares implementation tags for different graph representations. - -#pragma once - -#include "gl/traits.hpp" - -namespace gl { - -namespace impl { - -struct list_t; - -struct flat_list_t; - -struct matrix_t; - -struct flat_matrix_t; - -} // namespace impl - -namespace traits { - -/// @ingroup GL GL-Traits -/// @brief Validates if a type is one of the defined graph implementation tags. -/// -/// This concept is used to constrain template parameters that are expected to be -/// specific graph implementation tags, ensuring type safety and clear intent in template usage. -/// -/// The valid tags include: -/// - @ref gl::impl::list_t "impl::list_t": Represents a standard adjacency list implementation. -/// - @ref gl::impl::flat_list_t "impl::flat_list_t": Represents a flattened adjacency list implementation. -/// - @ref gl::impl::matrix_t "impl::matrix_t": Represents a standard adjacency matrix implementation. -/// - @ref gl::impl::flat_matrix_t "impl::flat_matrix_t": Represents a flattened adjacency matrix implementation. -/// -/// @tparam T The type to evaluate against the concept. -template -concept c_graph_impl_tag = - c_one_of; - -} // namespace traits - -} // namespace gl diff --git a/include/gl/decl/repr_tags.hpp b/include/gl/decl/repr_tags.hpp new file mode 100644 index 00000000..827f1fcf --- /dev/null +++ b/include/gl/decl/repr_tags.hpp @@ -0,0 +1,47 @@ +// Copyright (c) 2024-2026 Jakub Musiał +// This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl). +// Licensed under the MIT License. See the LICENSE file in the project root for full license information. + +/// @file gl/decl/repr_tags.hpp +/// @brief Forward declares representation tags for different graph representations. + +#pragma once + +#include "gl/traits.hpp" + +namespace gl { + +namespace repr { + +struct list_t; + +struct flat_list_t; + +struct matrix_t; + +struct flat_matrix_t; + +} // namespace repr + +namespace traits { + +/// @ingroup GL-Traits +/// @brief Validates if a type is one of the defined graph representation tags. +/// +/// This concept is used to constrain template parameters that are expected to be +/// specific graph representation tags, ensuring type safety and clear intent in template usage. +/// +/// The valid tags include: +/// - @ref gl::repr::list_t "repr::list_t": Represents a standard adjacency list representation. +/// - @ref gl::repr::flat_list_t "repr::flat_list_t": Represents a flattened adjacency list representation. +/// - @ref gl::repr::matrix_t "repr::matrix_t": Represents a standard adjacency matrix representation. +/// - @ref gl::repr::flat_matrix_t "repr::flat_matrix_t": Represents a flattened adjacency matrix representation. +/// +/// @tparam T The type to evaluate against the concept. +template +concept c_graph_repr_tag = + c_one_of; + +} // namespace traits + +} // namespace gl diff --git a/include/gl/directional_tags.hpp b/include/gl/directional_tags.hpp index 104a91bd..9aa500ef 100644 --- a/include/gl/directional_tags.hpp +++ b/include/gl/directional_tags.hpp @@ -19,7 +19,7 @@ struct undirected_t; namespace traits { -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Validates if a type is a valid graph directional tag. /// /// The valid graph directional tags are @ref gl::directed_t "directed_t" and @ref gl::undirected_t "undirected_t". @@ -40,7 +40,7 @@ class edge_descriptor; namespace traits { -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept to validate if a type is an instantiation of @ref gl::edge_descriptor "edge_descriptor" with the @ref gl::directed_t "directed_t" tag. /// @tparam T The type to evaluate against the concept. template @@ -48,7 +48,7 @@ concept c_directed_edge = c_instantiation_of and std::same_as; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept to validate if a type is an instantiation of @ref gl::edge_descriptor "edge_descriptor" with the @ref gl::undirected_t "undirected_t" tag. /// @tparam T The type to evaluate against the concept. template @@ -58,7 +58,7 @@ concept c_undirected_edge = } // namespace traits -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @headerfile gl/directional_tags.hpp /// @brief The tag type representing a directed graph configuration. /// @@ -100,7 +100,7 @@ struct directed_t { } }; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @headerfile gl/directional_tags.hpp /// @brief The tag type representing an undirected graph configuration. /// diff --git a/include/gl/edge_descriptor.hpp b/include/gl/edge_descriptor.hpp index 70edafec..a567cf12 100644 --- a/include/gl/edge_descriptor.hpp +++ b/include/gl/edge_descriptor.hpp @@ -19,7 +19,7 @@ namespace gl { -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief A lightweight wrapper representing a graph edge with its endpoints and optional properties. /// /// The `edge_descriptor` class provides a type-safe and efficient way to represent @@ -372,7 +372,7 @@ class edge_descriptor final { std::reference_wrapper> _properties; }; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Type alias for a directed edge descriptor. /// /// Pre-binds the `DirectionalTag` of `edge_descriptor` to `directed_t`. @@ -387,7 +387,7 @@ template < traits::c_id_type IdType = default_id_type> using directed_edge = edge_descriptor; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Type alias for an undirected edge descriptor. /// /// Pre-binds the `DirectionalTag` of `edge_descriptor` to `undirected_t`. diff --git a/include/gl/graph.hpp b/include/gl/graph.hpp index f602bbd7..a41a3e7d 100644 --- a/include/gl/graph.hpp +++ b/include/gl/graph.hpp @@ -11,10 +11,10 @@ #include "gl/constants.hpp" #include "gl/directional_tags.hpp" #include "gl/graph_traits.hpp" -#include "gl/impl/impl_tags.hpp" #include "gl/io/graph_fmt_traits.hpp" #include "gl/io/options.hpp" #include "gl/io/options_manip.hpp" +#include "gl/repr_tags.hpp" #include "gl/traits.hpp" #include "gl/util/ranges.hpp" @@ -30,63 +30,63 @@ class graph; namespace traits { -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept checking if a type is an instantiation of the generic @ref "gl::graph" graph class. template concept c_graph = c_instantiation_of; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept checking if a graph is directed. /// @see gl::directed_t "directed_t" : For the directional tag used to specify directed graph configuration. template concept c_directed_graph = c_graph and c_directed_edge; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept checking if a graph is undirected. /// @see gl::undirected_t "undirected_t" : For the directional tag used to specify undirected graph configuration. template concept c_undirected_graph = c_graph and c_undirected_edge; -/// @ingroup GL GL-Traits -/// @brief Concept checking if a graph utilizes the standard adjacency list implementation. -/// @see gl::impl::list_t "list_t" : For the implementation tag used to specify the standard adjacency list representation. +/// @ingroup GL-Traits +/// @brief Concept checking if a graph utilizes the standard adjacency list representation. +/// @see gl::repr::list_t "list_t" : For the representation tag used to specify the standard adjacency list representation. template -concept c_list_graph = c_graph and std::same_as; +concept c_list_graph = c_graph and std::same_as; -/// @ingroup GL GL-Traits -/// @brief Concept checking if a graph utilizes the flattened adjacency list implementation. -/// @see gl::impl::flat_list_t "flat_list_t" : For the implementation tag used to specify the flattened adjacency list representation. +/// @ingroup GL-Traits +/// @brief Concept checking if a graph utilizes the flattened adjacency list representation. +/// @see gl::repr::flat_list_t "flat_list_t" : For the representation tag used to specify the flattened adjacency list representation. template concept c_flat_list_graph = - c_graph and std::same_as; + c_graph and std::same_as; -/// @ingroup GL GL-Traits -/// @brief Concept checking if a graph utilizes any list-based adjacency implementation. +/// @ingroup GL-Traits +/// @brief Concept checking if a graph utilizes any list-based adjacency representation. /// ### See Also -/// - @ref gl::impl::list_t "list_t" : For the implementation tag used to specify the standard adjacency list representation. -/// - @ref gl::impl::flat_list_t "flat_list_t" : For the implementation tag used to specify the flattened adjacency list representation. +/// - @ref gl::repr::list_t "list_t" : For the representation tag used to specify the standard adjacency list representation. +/// - @ref gl::repr::flat_list_t "flat_list_t" : For the representation tag used to specify the flattened adjacency list representation. template concept c_adjacency_list_graph = c_list_graph or c_flat_list_graph; -/// @ingroup GL GL-Traits -/// @brief Concept checking if a graph utilizes the standard adjacency matrix implementation. -/// @see gl::impl::matrix_t "matrix_t" : For the implementation tag used to specify the standard adjacency matrix representation. +/// @ingroup GL-Traits +/// @brief Concept checking if a graph utilizes the standard adjacency matrix representation. +/// @see gl::repr::matrix_t "matrix_t" : For the representation tag used to specify the standard adjacency matrix representation. template concept c_matrix_graph = - c_graph and std::same_as; + c_graph and std::same_as; -/// @ingroup GL GL-Traits -/// @brief Concept checking if a graph utilizes the flattened adjacency matrix implementation. -/// @see gl::impl::flat_matrix_t "flat_matrix_t" : For the implementation tag used to specify the flattened adjacency matrix representation. +/// @ingroup GL-Traits +/// @brief Concept checking if a graph utilizes the flattened adjacency matrix representation. +/// @see gl::repr::flat_matrix_t "flat_matrix_t" : For the representation tag used to specify the flattened adjacency matrix representation. template concept c_flat_matrix_graph = - c_graph and std::same_as; + c_graph and std::same_as; -/// @ingroup GL GL-Traits -/// @brief Concept checking if a graph utilizes any matrix-based adjacency implementation. +/// @ingroup GL-Traits +/// @brief Concept checking if a graph utilizes any matrix-based adjacency representation. /// ### See Also -/// - @ref gl::impl::matrix_t "matrix_t" : For the implementation tag used to specify the standard adjacency matrix representation. -/// - @ref gl::impl::flat_matrix_t "flat_matrix_t" : For the implementation tag used to specify the flattened adjacency matrix representation. +/// - @ref gl::repr::matrix_t "matrix_t" : For the representation tag used to specify the standard adjacency matrix representation. +/// - @ref gl::repr::flat_matrix_t "flat_matrix_t" : For the representation tag used to specify the flattened adjacency matrix representation. template concept c_adjacency_matrix_graph = c_matrix_graph or c_flat_matrix_graph; @@ -95,17 +95,17 @@ concept c_adjacency_matrix_graph = c_matrix_graph or c_flat_matrix_graph; template [[nodiscard]] Graph clone(const Graph& source); -template +template [[nodiscard]] auto to(Graph&& source); namespace detail { -template +template struct to_impl; } // namespace detail -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief The generic graph container using a policy-based architecture. /// /// This class relies on the provided `GraphTraits` to determine its behavior, element @@ -114,15 +114,15 @@ struct to_impl; /// /// ### Key Features /// - **Policy-based design**: Behavior and representation are determined by `GraphTraits`. -/// - **Zero-cost Abstractions**: Core query logic is resolved at compile time through implementation tags and static dispatch, removing unnecessary overhead. +/// - **Zero-cost Abstractions**: Core query logic is resolved at compile time through representation tags and static dispatch, removing unnecessary overhead. /// - **Configurable directionality**: Support for both directed and undirected graphs. /// - **Multiple representations**: Choose the underlying memory model that best suits your algorithmic and cache-locality needs: -/// - @ref gl::impl::list_t "list_t": Standard adjacency list. -/// - @ref gl::impl::flat_list_t "flat_list_t": Flattened adjacency list. -/// - @ref gl::impl::matrix_t "matrix_t": Standard adjacency matrix. -/// - @ref gl::impl::flat_matrix_t "flat_matrix_t": Flattened adjacency matrix. +/// - @ref gl::repr::list_t "list_t": Standard adjacency list. +/// - @ref gl::repr::flat_list_t "flat_list_t": Flattened adjacency list. +/// - @ref gl::repr::matrix_t "matrix_t": Standard adjacency matrix. +/// - @ref gl::repr::flat_matrix_t "flat_matrix_t": Flattened adjacency matrix. /// - **Property support**: Vertices and edges can carry arbitrary properties. -/// - **Unified API**: Consistent interface regardless of the underlying implementation. +/// - **Unified API**: Consistent interface regardless of the underlying representation. /// - **Standard Range Support**: Exposes lightweight views compliant with C++20 `std::ranges`, enabling functional-style iteration and algorithms. /// /// ### Basic Definitions @@ -197,7 +197,7 @@ struct to_impl; /// - @ref gl::directed_graph "directed_graph" : Convenience alias for directed graphs. /// - @ref gl::undirected_graph "undirected_graph" : Convenience alias for undirected graphs. /// - @ref gl::clone "clone" : Create a deep copy of a graph. -/// - @ref gl::to "to" : Convert a graph to a different implementation. +/// - @ref gl::to "to" : Convert a graph to a different representation. /// /// > [!IMPORTANT] Copy Semantics /// > @@ -218,11 +218,11 @@ class graph final { /// @brief Type tag specifying the directionality of the graph. using directional_tag = typename traits_type::directional_tag; - /// @brief Type tag indicating the underlying implementation model. - using implementation_tag = typename traits_type::implementation_tag; + /// @brief Type tag indicating the underlying representation model. + using representation_tag = typename traits_type::representation_tag; - /// @brief The underlying implementation type matching the directional tag. - using implementation_type = typename implementation_tag::template type; + /// @brief The underlying representation type matching the directional tag. + using implementation_type = typename representation_tag::template type; friend implementation_type; /// @brief Integral type used to identify vertices and edges. @@ -1154,11 +1154,11 @@ class graph final { friend Graph clone(const Graph& source); /// @brief Friend declaration providing access for graph target conversions. - template + template friend auto to(Graph&& source); /// @brief Internal friend structure for `to` conversion operations. - template + template friend struct detail::to_impl; private: @@ -1409,7 +1409,7 @@ class graph final { // --- general graph utility --- -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Creates a deep copy of the given graph. /// @tparam Graph The type of the graph. /// @param source The graph instance to clone. @@ -1419,28 +1419,28 @@ template return Graph(source); } -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Convenience alias for defining a directed graph. template < traits::c_properties VertexProperties = empty_properties, traits::c_properties EdgeProperties = empty_properties, - traits::c_graph_impl_tag ImplTag = impl::list_t, + traits::c_graph_repr_tag ReprTag = repr::list_t, traits::c_id_type IdType = default_id_type> using directed_graph = - graph>; + graph>; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Convenience alias for defining a nundirected graph. template < traits::c_properties VertexProperties = empty_properties, traits::c_properties EdgeProperties = empty_properties, - traits::c_graph_impl_tag ImplTag = impl::list_t, + traits::c_graph_repr_tag ReprTag = repr::list_t, traits::c_id_type IdType = default_id_type> using undirected_graph = - graph>; + graph>; -/// @ingroup GL GL-Core -/// @brief Convenience alias for defining a graph utilizing an adjacency list implementation model. +/// @ingroup GL-Core +/// @brief Convenience alias for defining a graph utilizing an adjacency list representation model. template < traits::c_graph_directional_tag DirectionalTag = directed_t, traits::c_properties VertexProperties = empty_properties, @@ -1449,8 +1449,8 @@ template < using list_graph = graph>; -/// @ingroup GL GL-Core -/// @brief Convenience alias for defining a graph utilizing an adjacency matrix implementation model. +/// @ingroup GL-Core +/// @brief Convenience alias for defining a graph utilizing an adjacency matrix representation model. template < traits::c_graph_directional_tag DirectionalTag = directed_t, traits::c_properties VertexProperties = empty_properties, @@ -1459,8 +1459,8 @@ template < using matrix_graph = graph>; -/// @ingroup GL GL-Core -/// @brief Convenience alias for defining a graph utilizing a flattened adjacency list implementation model. +/// @ingroup GL-Core +/// @brief Convenience alias for defining a graph utilizing a flattened adjacency list representation model. template < traits::c_graph_directional_tag DirectionalTag = directed_t, traits::c_properties VertexProperties = empty_properties, @@ -1469,8 +1469,8 @@ template < using flat_list_graph = graph>; -/// @ingroup GL GL-Core -/// @brief Convenience alias for defining a graph utilizing a flattened adjacency matrix implementation model. +/// @ingroup GL-Core +/// @brief Convenience alias for defining a graph utilizing a flattened adjacency matrix representation model. template < traits::c_graph_directional_tag DirectionalTag = directed_t, traits::c_properties VertexProperties = empty_properties, @@ -1484,7 +1484,7 @@ using flat_matrix_graph = /// @brief Default numeric type representing distances between vertices in unweighted graphs. using default_vertex_distance_type = std::int64_t; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Utility trait to resolve the underlying distance or weight numeric type for a graph. template struct vertex_distance { @@ -1492,7 +1492,7 @@ struct vertex_distance { using type = default_vertex_distance_type; }; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Specialization resolving the specific weight type when edge properties contain weight attributes. template requires(traits::c_weight_properties_type) @@ -1501,12 +1501,12 @@ struct vertex_distance { using type = typename GraphType::edge_properties_type::weight_type; }; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Convenience alias to retrieve the appropriate distance numeric type from a graph structure. template using vertex_distance_type = typename vertex_distance::type; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Helper utility to safely retrieve the weight payload of an edge. /// /// Automatically returns a constant default if the graph representation carries no attached weight properties. diff --git a/include/gl/graph_traits.hpp b/include/gl/graph_traits.hpp index 1fc3fe93..af50ddd0 100644 --- a/include/gl/graph_traits.hpp +++ b/include/gl/graph_traits.hpp @@ -8,18 +8,18 @@ #pragma once #include "gl/decl/graph_traits.hpp" -#include "gl/decl/impl_tags.hpp" +#include "gl/decl/repr_tags.hpp" #include "gl/directional_tags.hpp" #include "gl/edge_descriptor.hpp" #include "gl/types/core.hpp" namespace gl { -/// @ingroup GL GL-Core -/// @brief Primary graph traits structure that encapsulates all necessary type information for graph implementations. +/// @ingroup GL-Core +/// @brief Primary graph traits structure that encapsulates all necessary type information for graph representations. /// /// This structure serves as the central point for defining the properties and types associated with a graph, -/// including directionality, vertex and edge properties, as well as implementation and identifier types. It is designed +/// including directionality, vertex and edge properties, as well as representation and identifier types. It is designed /// to be flexible and extensible, allowing users to customize their graph types by specifying different traits. /// /// ### Template Parameters @@ -28,15 +28,15 @@ namespace gl { /// | DirectionalTag | Specifies whether the graph is directed or undirected. | @ref gl::directed_t "directed_t" | [**c_graph_directional_tag**](gl_concepts.md#gl-traits-c-graph-directional-tag) | /// | VertexProperties | A type representing the properties associated with vertices in the graph. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) | /// | EdgeProperties | A type representing the properties associated with edges in the graph. | @ref gl::empty_properties "empty_properties" | [**c_properties**](gl_concepts.md#gl-traits-c-properties) | -/// | ImplTag | Specifies the graph implementation type (e.g., adjacency list, adjacency matrix). | @ref gl::impl::list_t "impl::list_t" | [**c_graph_impl_tag**](gl_concepts.md#gl-traits-c-graph-impl-tag) | +/// | ReprTag | Specifies the graph representation type (e.g., adjacency list, adjacency matrix). | @ref gl::repr::list_t "repr::list_t" | [**c_graph_repr_tag**](gl_concepts.md#gl-traits-c-graph-repr-tag) | /// | IdType | The type used for vertex and edge identifiers. | @ref gl::default_id_type "default_id_type" | [**c_id_type**](gl_concepts.md#gl-traits-c-id-type) | /// /// ### See Also -/// - Available implementation tags: -/// - @ref gl::impl::list_t "impl::list_t" : A standard adjacency list implementation. -/// - @ref gl::impl::flat_list_t "impl::flat_list_t" : A flattened adjacency list implementation. -/// - @ref gl::impl::matrix_t "impl::matrix_t" : A standard adjacency matrix implementation. -/// - @ref gl::impl::flat_matrix_t "impl::flat_matrix_t" : A flattened adjacency matrix implementation. +/// - Available representation tags: +/// - @ref gl::repr::list_t "repr::list_t" : A standard adjacency list representation. +/// - @ref gl::repr::flat_list_t "repr::flat_list_t" : A flattened adjacency list representation. +/// - @ref gl::repr::matrix_t "repr::matrix_t" : A standard adjacency matrix representation. +/// - @ref gl::repr::flat_matrix_t "repr::flat_matrix_t" : A flattened adjacency matrix representation. /// - @ref gl::directed_t "directed_t", @ref gl::undirected_t "undirected_t" : For the directional tags used to specify graph directionality. /// - @ref gl::vertex_descriptor "vertex_descriptor" : For the vertex descriptor type defined based on the graph traits. /// - @ref gl::edge_descriptor "edge_descriptor" : For the edge descriptor type defined based on the graph traits. @@ -52,13 +52,13 @@ template < traits::c_graph_directional_tag DirectionalTag = directed_t, traits::c_properties VertexProperties = empty_properties, traits::c_properties EdgeProperties = empty_properties, - traits::c_graph_impl_tag ImplTag = impl::list_t, + traits::c_graph_repr_tag ReprTag = repr::list_t, traits::c_id_type IdType = default_id_type> struct graph_traits { /// @brief The tag indicating the graph's directionality (directed or undirected). using directional_tag = DirectionalTag; - /// @brief The tag indicating the graph's implementation type (e.g., adjacency list, adjacency matrix). - using implementation_tag = ImplTag; + /// @brief The tag indicating the graph's representation type (e.g., adjacency list, adjacency matrix). + using representation_tag = ReprTag; /// @brief The type of graph element indentifiers (i.e. vertex and edge IDs). using id_type = IdType; @@ -73,17 +73,17 @@ struct graph_traits { using edge_properties_type = typename edge_type::properties_type; }; -/// @ingroup GL GL-Core -/// @brief Type alias for graph traits with an adjacency list implementation. +/// @ingroup GL-Core +/// @brief Type alias for graph traits with an adjacency list representation. /// /// This alias simplifies the specification of graph traits for graphs that use an adjacency list representation, /// allowing users to easily define their graph types with the desired properties and directionality while defaulting -/// to the adjacency list implementation. +/// to the adjacency list representation. /// /// > [!NOTE] Template parameters /// > /// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the -/// > `ImplTag` parameter fixed to @ref gl::impl::list_t "impl::list_t". This means that when using `list_graph_traits`, +/// > `ReprTag` parameter fixed to @ref gl::repr::list_t "repr::list_t". This means that when using `list_graph_traits`, /// > only the `DirectionalTag`, `VertexProperties`, `EdgeProperties`, and `IdType` parameters need to be specified. template < traits::c_graph_directional_tag DirectionalTag = directed_t, @@ -91,19 +91,19 @@ template < traits::c_properties EdgeProperties = empty_properties, traits::c_id_type IdType = default_id_type> using list_graph_traits = - graph_traits; + graph_traits; -/// @ingroup GL GL-Core -/// @brief Type alias for graph traits with a flattened adjacency list implementation. +/// @ingroup GL-Core +/// @brief Type alias for graph traits with a flattened adjacency list representation. /// /// This alias simplifies the specification of graph traits for graphs that use a flattened adjacency list representation, /// allowing users to easily define their graph types with the desired properties and directionality while defaulting -/// to the flattened adjacency list implementation. +/// to the flattened adjacency list representation. /// /// > [!NOTE] Template parameters /// > /// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the -/// > `ImplTag` parameter fixed to @ref gl::impl::flat_list_t "impl::flat_list_t". This means that when using `flat_list_graph_traits`, +/// > `ReprTag` parameter fixed to @ref gl::repr::flat_list_t "repr::flat_list_t". This means that when using `flat_list_graph_traits`, /// > only the `DirectionalTag`, `VertexProperties`, `EdgeProperties`, and `IdType` parameters need to be specified. template < traits::c_graph_directional_tag DirectionalTag = directed_t, @@ -111,19 +111,19 @@ template < traits::c_properties EdgeProperties = empty_properties, traits::c_id_type IdType = default_id_type> using flat_list_graph_traits = - graph_traits; + graph_traits; -/// @ingroup GL GL-Core -/// @brief Type alias for graph traits with an adjacency matrix implementation. +/// @ingroup GL-Core +/// @brief Type alias for graph traits with an adjacency matrix representation. /// /// This alias simplifies the specification of graph traits for graphs that use an adjacency matrix representation, /// allowing users to easily define their graph types with the desired properties and directionality while defaulting -/// to the adjacency matrix implementation. +/// to the adjacency matrix representation. /// /// > [!NOTE] Template parameters /// > /// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the -/// > `ImplTag` parameter fixed to @ref gl::impl::matrix_t "impl::matrix_t". This means that when using `matrix_graph_traits`, +/// > `ReprTag` parameter fixed to @ref gl::repr::matrix_t "repr::matrix_t". This means that when using `matrix_graph_traits`, /// > only the `DirectionalTag`, `VertexProperties`, `EdgeProperties`, and `IdType` parameters need to be specified. template < traits::c_graph_directional_tag DirectionalTag = directed_t, @@ -131,19 +131,19 @@ template < traits::c_properties EdgeProperties = empty_properties, traits::c_id_type IdType = default_id_type> using matrix_graph_traits = - graph_traits; + graph_traits; -/// @ingroup GL GL-Core -/// @brief Type alias for graph traits with a flattened adjacency matrix implementation. +/// @ingroup GL-Core +/// @brief Type alias for graph traits with a flattened adjacency matrix representation. /// /// This alias simplifies the specification of graph traits for graphs that use a flattened adjacency matrix representation, /// allowing users to easily define their graph types with the desired properties and directionality while defaulting -/// to the flattened adjacency matrix implementation. +/// to the flattened adjacency matrix representation. /// /// > [!NOTE] Template parameters /// > /// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the -/// > `ImplTag` parameter fixed to @ref gl::impl::flat_matrix_t "impl::flat_matrix_t". This means that when using `flat_matrix_graph_traits`, +/// > `ReprTag` parameter fixed to @ref gl::repr::flat_matrix_t "repr::flat_matrix_t". This means that when using `flat_matrix_graph_traits`, /// > only the `DirectionalTag`, `VertexProperties`, `EdgeProperties`, and `IdType` parameters need to be specified. template < traits::c_graph_directional_tag DirectionalTag = directed_t, @@ -151,93 +151,93 @@ template < traits::c_properties EdgeProperties = empty_properties, traits::c_id_type IdType = default_id_type> using flat_matrix_graph_traits = - graph_traits; + graph_traits; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Type alias for graph traits with an directed graph configuration. /// /// This alias simplifies the specification of graph traits for directed graphs, allowing users to easily define their -/// graph types with the desired properties and implementation while defaulting to a directed configuration. +/// graph types with the desired properties and representation while defaulting to a directed configuration. /// /// > [!NOTE] Template parameters /// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the /// > `DirectionalTag` parameter fixed to @ref gl::directed_t "directed_t". This means that when using `directed_graph_traits`, -/// > only the `VertexProperties`, `EdgeProperties`, 'ImplTag', and `IdType` parameters need to be specified. +/// > only the `VertexProperties`, `EdgeProperties`, 'ReprTag', and `IdType` parameters need to be specified. template < traits::c_properties VertexProperties = empty_properties, traits::c_properties EdgeProperties = empty_properties, - traits::c_graph_impl_tag ImplTag = impl::list_t, + traits::c_graph_repr_tag ReprTag = repr::list_t, traits::c_id_type IdType = default_id_type> using directed_graph_traits = - graph_traits; + graph_traits; -/// @ingroup GL GL-Core +/// @ingroup GL-Core /// @brief Type alias for graph traits with an undirected graph configuration. /// /// This alias simplifies the specification of graph traits for undirected graphs, allowing users to easily define their -/// graph types with the desired properties and implementation while defaulting to an undirected configuration. +/// graph types with the desired properties and representation while defaulting to an undirected configuration. /// /// > [!NOTE] Template parameters /// > The template parameters for this alias are the same as those for @ref gl::graph_traits "graph_traits", with the /// > `DirectionalTag` parameter fixed to @ref gl::undirected_t "undirected_t". This means that when using `undirected_graph_traits`, -/// > only the `VertexProperties`, `EdgeProperties`, 'ImplTag', and `IdType` parameters need to be specified. +/// > only the `VertexProperties`, `EdgeProperties`, 'ReprTag', and `IdType` parameters need to be specified. template < traits::c_properties VertexProperties = empty_properties, traits::c_properties EdgeProperties = empty_properties, - traits::c_graph_impl_tag ImplTag = impl::list_t, + traits::c_graph_repr_tag ReprTag = repr::list_t, traits::c_id_type IdType = default_id_type> using undirected_graph_traits = - graph_traits; + graph_traits; namespace traits { -/// @ingroup GL GL-Traits -/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a list implementation. +/// @ingroup GL-Traits +/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a list representation. /// @tparam TraitsType The type to evaluate against the concept. template concept c_list_graph_traits = c_instantiation_of - and std::same_as; + and std::same_as; -/// @ingroup GL GL-Traits -/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a flattened adjacency list implementation. +/// @ingroup GL-Traits +/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a flattened adjacency list representation. /// @tparam TraitsType The type to evaluate against the concept. template concept c_flat_list_graph_traits = c_instantiation_of - and std::same_as; + and std::same_as; -/// @ingroup GL GL-Traits -/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with an adjacency list implementation (either standard or flattened). +/// @ingroup GL-Traits +/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with an adjacency list representation (either standard or flattened). /// @tparam TraitsType The type to evaluate against the concept. template concept c_adjacency_list_graph_traits = c_list_graph_traits or c_flat_list_graph_traits; -/// @ingroup GL GL-Traits -/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a matrix implementation. +/// @ingroup GL-Traits +/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a matrix representation. /// @tparam TraitsType The type to evaluate against the concept. template concept c_matrix_graph_traits = c_instantiation_of - and std::same_as; + and std::same_as; -/// @ingroup GL GL-Traits -/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a flattened adjacency matrix implementation. +/// @ingroup GL-Traits +/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a flattened adjacency matrix representation. /// @tparam TraitsType The type to evaluate against the concept. template concept c_flat_matrix_graph_traits = c_instantiation_of - and std::same_as; + and std::same_as; -/// @ingroup GL GL-Traits -/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a matrix implementation (either standard or flattened). +/// @ingroup GL-Traits +/// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a matrix representation (either standard or flattened). /// @tparam TraitsType The type to evaluate against the concept. template concept c_adjacency_matrix_graph_traits = c_matrix_graph_traits or c_flat_matrix_graph_traits; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with a directed graph configuration. /// @tparam TraitsType The type to evaluate against the concept. template @@ -245,7 +245,7 @@ concept c_directed_graph_traits = c_instantiation_of and std::same_as; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept to validate if a type is an instantiation of @ref gl::graph_traits "graph_traits" with an undirected graph configuration. /// @tparam TraitsType The type to evaluate against the concept. template diff --git a/include/gl/impl/adjacency_list.hpp b/include/gl/impl/adjacency_list.hpp index e96037ae..f58cb73f 100644 --- a/include/gl/impl/adjacency_list.hpp +++ b/include/gl/impl/adjacency_list.hpp @@ -20,7 +20,7 @@ namespace gl { namespace detail { -template +template struct to_impl; } // namespace detail @@ -30,7 +30,7 @@ namespace impl { template class adjacency_list final { public: - using implementation_tag = typename GraphTraits::implementation_tag; + using representation_tag = typename GraphTraits::representation_tag; using id_type = typename GraphTraits::id_type; using vertex_type = typename GraphTraits::vertex_type; @@ -270,7 +270,7 @@ class adjacency_list final { // --- friend declarations --- - template + template friend struct gl::detail::to_impl; #ifdef GL_TESTING diff --git a/include/gl/impl/adjacency_matrix.hpp b/include/gl/impl/adjacency_matrix.hpp index 88e555d7..2c3204ff 100644 --- a/include/gl/impl/adjacency_matrix.hpp +++ b/include/gl/impl/adjacency_matrix.hpp @@ -20,7 +20,7 @@ namespace gl { namespace detail { -template +template struct to_impl; } // namespace detail @@ -30,7 +30,7 @@ namespace impl { template class adjacency_matrix final { public: - using implementation_tag = typename GraphTraits::implementation_tag; + using representation_tag = typename GraphTraits::representation_tag; using id_type = typename GraphTraits::id_type; using vertex_type = typename GraphTraits::vertex_type; @@ -284,7 +284,7 @@ class adjacency_matrix final { // --- friend declarations --- - template + template friend struct gl::detail::to_impl; #ifdef GL_TESTING diff --git a/include/gl/impl/specialized/adjacency_list.hpp b/include/gl/impl/specialized/adjacency_list.hpp index acc37e87..6927fdfb 100644 --- a/include/gl/impl/specialized/adjacency_list.hpp +++ b/include/gl/impl/specialized/adjacency_list.hpp @@ -5,7 +5,7 @@ #pragma once #include "gl/constants.hpp" -#include "gl/decl/impl_tags.hpp" +#include "gl/decl/repr_tags.hpp" #include "gl/graph_traits.hpp" #include "gl/traits.hpp" #include "gl/types/core.hpp" @@ -380,7 +380,7 @@ struct adjacency_list_impl_traits { template AdjacencyList> requires traits::c_directed_edge - and std::same_as + and std::same_as struct adjacency_list_impl_traits { using type = directed_adjacency_list; @@ -390,7 +390,7 @@ struct adjacency_list_impl_traits { template AdjacencyList> requires traits::c_undirected_edge - and std::same_as + and std::same_as struct adjacency_list_impl_traits { using type = undirected_adjacency_list; diff --git a/include/gl/impl/specialized/adjacency_matrix.hpp b/include/gl/impl/specialized/adjacency_matrix.hpp index bedcc582..5e21672f 100644 --- a/include/gl/impl/specialized/adjacency_matrix.hpp +++ b/include/gl/impl/specialized/adjacency_matrix.hpp @@ -7,7 +7,7 @@ #include "gl/attributes/diagnostics.hpp" #include "gl/attributes/force_inline.hpp" #include "gl/constants.hpp" -#include "gl/decl/impl_tags.hpp" +#include "gl/decl/repr_tags.hpp" #include "gl/graph_traits.hpp" #include "gl/types/core.hpp" #include "gl/util/ranges.hpp" @@ -449,7 +449,8 @@ struct adjacency_matrix_impl_traits { }; template AdjacencyMatrix> -requires(traits::c_directed_edge) +requires traits::c_directed_edge + and std::same_as struct adjacency_matrix_impl_traits { using type = directed_adjacency_matrix; @@ -458,7 +459,8 @@ struct adjacency_matrix_impl_traits { }; template AdjacencyMatrix> -requires(traits::c_undirected_edge) +requires traits::c_undirected_edge + and std::same_as struct adjacency_matrix_impl_traits { using type = undirected_adjacency_matrix; diff --git a/include/gl/impl/specialized/flat_adjacency_list.hpp b/include/gl/impl/specialized/flat_adjacency_list.hpp index 013a704b..9424a05a 100644 --- a/include/gl/impl/specialized/flat_adjacency_list.hpp +++ b/include/gl/impl/specialized/flat_adjacency_list.hpp @@ -5,7 +5,7 @@ #pragma once #include "gl/constants.hpp" -#include "gl/decl/impl_tags.hpp" +#include "gl/decl/repr_tags.hpp" #include "gl/graph_traits.hpp" #include "gl/impl/specialized/adjacency_list.hpp" #include "gl/types/flat_jagged_vector.hpp" @@ -352,7 +352,7 @@ struct undirected_flat_adjacency_list { template AdjacencyList> requires traits::c_directed_edge - and std::same_as + and std::same_as struct adjacency_list_impl_traits { using type = directed_flat_adjacency_list; @@ -362,7 +362,7 @@ struct adjacency_list_impl_traits { template AdjacencyList> requires traits::c_undirected_edge - and std::same_as + and std::same_as struct adjacency_list_impl_traits { using type = undirected_flat_adjacency_list; diff --git a/include/gl/impl/specialized/flat_adjacency_matrix.hpp b/include/gl/impl/specialized/flat_adjacency_matrix.hpp index e12d737f..a87e78dc 100644 --- a/include/gl/impl/specialized/flat_adjacency_matrix.hpp +++ b/include/gl/impl/specialized/flat_adjacency_matrix.hpp @@ -7,7 +7,7 @@ #include "gl/attributes/diagnostics.hpp" #include "gl/attributes/force_inline.hpp" #include "gl/constants.hpp" -#include "gl/decl/impl_tags.hpp" +#include "gl/decl/repr_tags.hpp" #include "gl/graph_traits.hpp" #include "gl/impl/specialized/adjacency_matrix.hpp" #include "gl/types/core.hpp" @@ -431,7 +431,7 @@ struct undirected_flat_adjacency_matrix { template AdjacencyMatrix> requires traits::c_directed_edge - and std::same_as + and std::same_as struct adjacency_matrix_impl_traits { using type = directed_flat_adjacency_matrix; @@ -441,7 +441,7 @@ struct adjacency_matrix_impl_traits { template AdjacencyMatrix> requires traits::c_undirected_edge - and std::same_as + and std::same_as struct adjacency_matrix_impl_traits { using type = undirected_flat_adjacency_matrix; diff --git a/include/gl/io/graph_fio.hpp b/include/gl/io/graph_fio.hpp index b6e68e9a..49440c6b 100644 --- a/include/gl/io/graph_fio.hpp +++ b/include/gl/io/graph_fio.hpp @@ -15,14 +15,14 @@ namespace gl { namespace io { -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Tag type specifying that a file should be opened in strictly write (truncate) mode. /// /// When using this mode, the operation will intentionally throw an exception if the target file already exists /// to prevent accidental data overwrites. struct write {}; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Tag type specifying that a file should be opened in append mode. /// /// When using this mode, the operation will append data to an existing file. It will throw an exception @@ -33,7 +33,7 @@ struct append {}; namespace traits { -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Concept checking if a provided type is a valid file I/O save mode. /// @see gl::io::write "write" /// @see gl::io::append "append" @@ -112,7 +112,7 @@ requires(std::same_as) } // namespace detail -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Serializes and saves a graph to a file. /// /// Saves the graph topology and optionally its properties using the Graph Specification Format (GSF). @@ -141,7 +141,7 @@ void save( file << graph; } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Deserializes and loads a graph from a file. /// /// Instantiates a new graph populated with the topology and properties read from the target GSF file. diff --git a/include/gl/io/options.hpp b/include/gl/io/options.hpp index 59658b9d..c78d525a 100644 --- a/include/gl/io/options.hpp +++ b/include/gl/io/options.hpp @@ -25,7 +25,7 @@ inline constexpr iword_type layout_options_mask = } // namespace detail -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to enable concise graph formatting. /// /// Clears all layout-specific flags to default back to a compact representation. @@ -33,7 +33,7 @@ inline constexpr iword_type layout_options_mask = /// @hideinitializer inline constexpr options_manip concise{0ul, detail::layout_options_mask}; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to enable verbose graph formatting. /// /// Modifies the stream state to output detailed structural information. @@ -43,7 +43,7 @@ inline constexpr options_manip verbose{ detail::build_mask(detail::option_bit::verbose), detail::layout_options_mask }; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to enable the Graph Specification Format (GSF). /// /// Modifies the stream to output or expect data matching the precise internal parsing format used for serialization and deserialization. @@ -53,45 +53,45 @@ inline constexpr options_manip spec_fmt{ detail::build_mask(detail::option_bit::spec_fmt), detail::layout_options_mask }; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to enable the processing of vertex properties. /// @hideinitializer inline constexpr options_manip with_vertex_properties = set_options(detail::option_bit::with_vertex_properties); -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to disable the processing of vertex properties. /// @hideinitializer inline constexpr options_manip without_vertex_properties = clear_options(detail::option_bit::with_vertex_properties); -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to enable the processing of edge properties. /// @hideinitializer inline constexpr options_manip with_edge_properties = set_options(detail::option_bit::with_connection_properties); -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to disable the processing of edge properties. /// @hideinitializer inline constexpr options_manip without_edge_properties = clear_options(detail::option_bit::with_connection_properties); -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to enable the processing of both vertex and edge properties simultaneously. /// @hideinitializer inline constexpr options_manip with_properties = set_options( detail::option_bit::with_vertex_properties, detail::option_bit::with_connection_properties ); -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to disable the processing of both vertex and edge properties simultaneously. /// @hideinitializer inline constexpr options_manip without_properties = clear_options( detail::option_bit::with_vertex_properties, detail::option_bit::with_connection_properties ); -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief @ref gl::io::options_manip "Stream manipulator" to reset all custom graph formatting flags back to their default states. /// @hideinitializer inline constexpr options_manip default_options{0ul, ~static_cast(0)}; diff --git a/include/gl/io/options_manip.hpp b/include/gl/io/options_manip.hpp index a9ec3e4d..4a1f37b3 100644 --- a/include/gl/io/options_manip.hpp +++ b/include/gl/io/options_manip.hpp @@ -15,23 +15,23 @@ namespace gl::io { -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Type used for standard I/O stream custom index allocation (`std::ios_base::xalloc`). using index_type = int; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Type used for storing custom option flags within standard I/O streams. using iword_type = long; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Type representing the zero-indexed position of a specific option bit. using bit_position_type = unsigned; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Base bit representing the a single position in an `iword` flag map. inline constexpr iword_type iword_bit = 1ul; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief A custom stream manipulator for modifying formatting options on standard I/O streams. /// /// Utilizing `std::ios_base::xalloc` and the `iword` map, this class safely injects custom formatting @@ -129,7 +129,7 @@ template } // namespace detail -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Creates a stream manipulator that enables the specified option bits. /// @tparam Args Variadic template arguments representing the bits to set. /// @param bits The specific options/bits to enable. @@ -139,7 +139,7 @@ template return options_manip{detail::build_mask(bits...), 0ul}; } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Creates a stream manipulator that enables the specified option bits from a list. /// @tparam T The type of the bits. /// @param bits An initializer list containing the options/bits to enable. @@ -149,7 +149,7 @@ template return options_manip{detail::build_mask_from(bits), 0ul}; } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Creates a stream manipulator that disables the specified option bits. /// @tparam Args Variadic template arguments representing the bits to clear. /// @param bits The specific options/bits to disable. @@ -159,7 +159,7 @@ template return options_manip{0ul, detail::build_mask(bits...)}; } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Creates a stream manipulator that disables the specified option bits from a list. /// @tparam T The type of the bits. /// @param bits An initializer list containing the options/bits to disable. @@ -169,7 +169,7 @@ template return options_manip{0ul, detail::build_mask_from(bits)}; } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Convenience wrapper to check if a specific option bit is set on the stream. /// @param stream The stream to check. /// @param bit_position The numeric position of the bit to verify. @@ -180,7 +180,7 @@ template return options_manip::is_option_set(stream, bit_position); } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Convenience wrapper to check if a specific enum-based option is set on the stream. /// @param stream The stream to check. /// @param bit The scoped enum value representing the bit to verify. @@ -191,7 +191,7 @@ template return options_manip::is_option_set(stream, bit); } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Convenience wrapper to check if a combined bitmask of options is set on the stream. /// @param stream The stream to check. /// @param bitmask The exact bitmask to verify. @@ -200,7 +200,7 @@ template return options_manip::are_options_set(stream, bitmask); } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Convenience wrapper to check if multiple specific options are simultaneously set. /// @tparam Args Variadic template arguments representing the bits. /// @param stream The stream to check. @@ -211,7 +211,7 @@ template return options_manip::are_options_set(stream, detail::build_mask(bits...)); } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Convenience wrapper to check if multiple specific options from a list are simultaneously set. /// @tparam T The type of the elements in the initializer list. /// @param stream The stream to check. diff --git a/include/gl/io/ranges.hpp b/include/gl/io/ranges.hpp index ad1e8834..864af64c 100644 --- a/include/gl/io/ranges.hpp +++ b/include/gl/io/ranges.hpp @@ -12,7 +12,7 @@ namespace gl::io { -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief A customizable stream proxy for formatting and printing C++ ranges. /// /// This struct acts as a wrapper around any `std::ranges::range`, allowing it to be @@ -84,7 +84,7 @@ template range_formatter(R&& r, std::string_view, std::string_view, std::string_view) -> range_formatter>; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Factory function to format a range as a set. /// /// Wraps the range output in curly braces `{}` instead of standard brackets `[]`. @@ -112,7 +112,7 @@ auto set_formatter(R&& range, std::string_view sep = ", ") { return range_formatter{std::views::all(std::forward(range)), sep, "{", "}"}; } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Factory function to format a range as a multiline set. /// /// Outputs each element on a new line, bounded by curly braces `{}`. @@ -147,7 +147,7 @@ auto multiline_set_formatter(R&& range) { }; } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief A proxy object for concisely formatting large contiguous numeric ranges. /// /// Instead of iterating and printing every element of a massive sequence, this formatter @@ -195,7 +195,7 @@ struct implicit_range_formatter { } }; -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Factory function to create an implicit range formatter with a defined start and end. /// /// ### Example Usage @@ -226,7 +226,7 @@ template return implicit_range_formatter{first, last + static_cast(inclusive)}; } -/// @ingroup GL GL-IO +/// @ingroup GL-IO /// @brief Factory function to create an implicit range formatter starting from 0. /// /// ### Example Usage diff --git a/include/gl/impl/impl_tags.hpp b/include/gl/repr_tags.hpp similarity index 50% rename from include/gl/impl/impl_tags.hpp rename to include/gl/repr_tags.hpp index 6def0a62..5f4ee049 100644 --- a/include/gl/impl/impl_tags.hpp +++ b/include/gl/repr_tags.hpp @@ -2,67 +2,67 @@ // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl). // Licensed under the MIT License. See the LICENSE file in the project root for full license information. -/// @file gl/impl/impl_tags.hpp -/// @brief Defines implementation tags for different graph representations. +/// @file gl/repr_tags.hpp +/// @brief Defines representation tags for different graph representations. #pragma once -#include "gl/decl/impl_tags.hpp" +#include "gl/decl/repr_tags.hpp" #include "gl/impl/adjacency_list.hpp" #include "gl/impl/adjacency_matrix.hpp" -namespace gl::impl { +namespace gl::repr { -/// @ingroup GL GL-Core -/// @headerfile gl/impl/impl_tags.hpp -/// @brief Tag struct for the standard adjacency list graph implementation. +/// @ingroup GL-Core +/// @headerfile gl/repr_tags.hpp +/// @brief Tag struct for the standard adjacency list graph representation. struct list_t { - /// @brief Type alias for the adjacency list graph implementation based on the provided graph traits. + /// @brief Type alias for the adjacency list graph representation based on the provided graph traits. /// @tparam GraphTraits The graph traits for which to define the adjacency list type. - /// Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `list_t` as its implementation tag. + /// Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `list_t` as its representation tag. template GraphTraits> - requires(std::same_as) - using type = adjacency_list; + requires(std::same_as) + using type = impl::adjacency_list; }; -/// @ingroup GL GL-Core -/// @headerfile gl/impl/impl_tags.hpp -/// @brief Tag struct for the flattened adjacency list graph implementation. +/// @ingroup GL-Core +/// @headerfile gl/repr_tags.hpp +/// @brief Tag struct for the flattened adjacency list graph representation. /// ### See Also -/// - @ref gl::flat_jagged_vector "flat_jagged_vector" : For the data structure used for the underlying model implementation. +/// - @ref gl::flat_jagged_vector "flat_jagged_vector" : For the data structure used for the underlying model representation. struct flat_list_t { - /// @brief Type alias for the flattened adjacency list graph implementation based on the provided graph traits. + /// @brief Type alias for the flattened adjacency list graph representation based on the provided graph traits. /// @tparam GraphTraits The graph traits for which to define the flattened adjacency list type. - /// Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `flat_list_t` as its implementation tag. + /// Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `flat_list_t` as its representation tag. template GraphTraits> - requires(std::same_as) - using type = adjacency_list; + requires(std::same_as) + using type = impl::adjacency_list; }; -/// @ingroup GL GL-Core -/// @headerfile gl/impl/impl_tags.hpp -/// @brief Tag struct for the standard adjacency matrix graph implementation. +/// @ingroup GL-Core +/// @headerfile gl/repr_tags.hpp +/// @brief Tag struct for the standard adjacency matrix graph representation. struct matrix_t { - /// @brief Type alias for the adjacency matrix graph implementation based on the provided graph traits. + /// @brief Type alias for the adjacency matrix graph representation based on the provided graph traits. /// @tparam GraphTraits The graph traits for which to define the adjacency matrix type. - /// Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `matrix_t` as its implementation tag. + /// Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `matrix_t` as its representation tag. template GraphTraits> - requires(std::same_as) - using type = adjacency_matrix; + requires(std::same_as) + using type = impl::adjacency_matrix; }; -/// @ingroup GL GL-Core -/// @headerfile gl/impl/impl_tags.hpp -/// @brief Tag struct for the flattened adjacency matrix graph implementation. +/// @ingroup GL-Core +/// @headerfile gl/repr_tags.hpp +/// @brief Tag struct for the flattened adjacency matrix graph representation. /// ### See Also -/// - @ref gl::flat_matrix "flat_matrix" : For the data structure used for the underlying model implementation. +/// - @ref gl::flat_matrix "flat_matrix" : For the data structure used for the underlying model representation. struct flat_matrix_t { - /// @brief Type alias for the flattened adjacency matrix graph implementation based on the provided graph traits. + /// @brief Type alias for the flattened adjacency matrix graph representation based on the provided graph traits. /// @tparam GraphTraits The graph traits for which to define the flattened adjacency matrix type. - /// Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `flat_matrix_t` as its implementation tag. + /// Must be an instantiation of @ref gl::graph_traits "graph_traits" and have `flat_matrix_t` as its representation tag. template GraphTraits> - requires(std::same_as) - using type = adjacency_matrix; + requires(std::same_as) + using type = impl::adjacency_matrix; }; -} // namespace gl::impl +} // namespace gl::repr diff --git a/include/gl/topology/binary_tree.hpp b/include/gl/topology/binary_tree.hpp index 2285009d..88ce4b6c 100644 --- a/include/gl/topology/binary_tree.hpp +++ b/include/gl/topology/binary_tree.hpp @@ -30,7 +30,7 @@ constexpr size_type min_non_trivial_bin_tree_depth = 2uz; } // namespace detail -/// @ingroup GL GL-Topology +/// @ingroup GL-Topology /// @brief Generates a regular (regular) binary tree of a specified depth. /// /// A regular binary tree is a tree where all internal vertices have exactly two children @@ -78,11 +78,11 @@ template template [[nodiscard]] GraphType regular_binary_tree(size_type depth) { - using base_graph_type = traits::swap_impl_tag_t; - return to(regular_binary_tree(depth)); + using base_graph_type = traits::swap_repr_tag_t; + return to(regular_binary_tree(depth)); } -/// @ingroup GL GL-Topology +/// @ingroup GL-Topology /// @brief Generates a regular binary tree with bidirectional edges. /// /// For directed graphs, this function ensures that for every parent-to-child edge, @@ -136,8 +136,8 @@ template template [[nodiscard]] GraphType bidirectional_regular_binary_tree(size_type depth) { - using base_graph_type = traits::swap_impl_tag_t; - return to(bidirectional_regular_binary_tree(depth)); + using base_graph_type = traits::swap_repr_tag_t; + return to(bidirectional_regular_binary_tree(depth)); } } // namespace gl::topology diff --git a/include/gl/topology/bipartite.hpp b/include/gl/topology/bipartite.hpp index e16730f3..4d5f376d 100644 --- a/include/gl/topology/bipartite.hpp +++ b/include/gl/topology/bipartite.hpp @@ -10,11 +10,11 @@ #include "gl/constants.hpp" #include "gl/conversion.hpp" #include "gl/graph.hpp" -#include "gl/impl/impl_tags.hpp" +#include "gl/repr_tags.hpp" namespace gl::topology { -/// @ingroup GL GL-Topology +/// @ingroup GL-Topology /// @brief Generates a complete bipartite graph (biclique). /// /// A complete bipartite graph is a graph whose vertices are partitioned into two disjoint @@ -55,8 +55,8 @@ template template [[nodiscard]] GraphType biclique(size_type n_vertices_a, size_type n_vertices_b) { - using base_graph_type = traits::swap_impl_tag_t; - return to(biclique(n_vertices_a, n_vertices_b)); + using base_graph_type = traits::swap_repr_tag_t; + return to(biclique(n_vertices_a, n_vertices_b)); } } // namespace gl::topology diff --git a/include/gl/topology/clique.hpp b/include/gl/topology/clique.hpp index d769c810..7f928608 100644 --- a/include/gl/topology/clique.hpp +++ b/include/gl/topology/clique.hpp @@ -13,7 +13,7 @@ namespace gl::topology { -/// @ingroup GL GL-Topology +/// @ingroup GL-Topology /// @brief Generates a complete graph (clique). /// /// A complete graph is a simple graph in which every pair of distinct vertices is connected by an edge. @@ -50,8 +50,8 @@ template template [[nodiscard]] GraphType clique(size_type n_vertices) { - using base_graph_type = traits::swap_impl_tag_t; - return to(clique(n_vertices)); + using base_graph_type = traits::swap_repr_tag_t; + return to(clique(n_vertices)); } } // namespace gl::topology diff --git a/include/gl/topology/cycle.hpp b/include/gl/topology/cycle.hpp index f68e562f..73455022 100644 --- a/include/gl/topology/cycle.hpp +++ b/include/gl/topology/cycle.hpp @@ -13,7 +13,7 @@ namespace gl::topology { -/// @ingroup GL GL-Topology +/// @ingroup GL-Topology /// @brief Generates a regular cycle graph (ring topology). /// /// A cycle graph consists of a single closed chain of vertices. Vertex \f$v_i\f$ is connected @@ -45,11 +45,11 @@ template template [[nodiscard]] GraphType cycle(size_type n_vertices) { - using base_graph_type = traits::swap_impl_tag_t; - return to(cycle(n_vertices)); + using base_graph_type = traits::swap_repr_tag_t; + return to(cycle(n_vertices)); } -/// @ingroup GL GL-Topology +/// @ingroup GL-Topology /// @brief Generates a cycle graph with bidirectional edges. /// /// For directed graphs, this function creates a reciprocal edge for every forward edge @@ -90,8 +90,8 @@ template template [[nodiscard]] GraphType bidirectional_cycle(size_type n_vertices) { - using base_graph_type = traits::swap_impl_tag_t; - return to(bidirectional_cycle(n_vertices)); + using base_graph_type = traits::swap_repr_tag_t; + return to(bidirectional_cycle(n_vertices)); } } // namespace gl::topology diff --git a/include/gl/topology/path.hpp b/include/gl/topology/path.hpp index 1ffcf9f7..f0ef996e 100644 --- a/include/gl/topology/path.hpp +++ b/include/gl/topology/path.hpp @@ -13,7 +13,7 @@ namespace gl::topology { -/// @ingroup GL GL-Topology +/// @ingroup GL-Topology /// @brief Generates a regular path graph (linear topology). /// /// A path graph consists of a simple linear sequence of vertices. Vertex \f$v_i\f$ is connected @@ -45,11 +45,11 @@ template template [[nodiscard]] GraphType path(size_type n_vertices) { - using base_graph_type = traits::swap_impl_tag_t; - return to(path(n_vertices)); + using base_graph_type = traits::swap_repr_tag_t; + return to(path(n_vertices)); } -/// @ingroup GL GL-Topology +/// @ingroup GL-Topology /// @brief Generates a path graph with bidirectional edges. /// /// For directed graphs, this function creates reciprocal edges along the linear sequence, @@ -90,8 +90,8 @@ template template [[nodiscard]] GraphType bidirectional_path(size_type n_vertices) { - using base_graph_type = traits::swap_impl_tag_t; - return to(bidirectional_path(n_vertices)); + using base_graph_type = traits::swap_repr_tag_t; + return to(bidirectional_path(n_vertices)); } } // namespace gl::topology diff --git a/include/gl/traits.hpp b/include/gl/traits.hpp index 571346e8..40d8a713 100644 --- a/include/gl/traits.hpp +++ b/include/gl/traits.hpp @@ -16,7 +16,7 @@ namespace gl::traits { -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Type trait to check if a type is an instantiation of a specific class template. /// @tparam T The type to check. /// @tparam Template The class template to match against. @@ -25,58 +25,58 @@ namespace gl::traits { template typename Template> struct is_instantiation_of : std::false_type {}; -/// @ingroup GL GL-Traits +/// @ingroup GL-Traits /// @brief Specialization of the @ref gl::traits::is_instantiation_of "is_instantiation_of" trait /// for when the type is an instantiation of the provided class template. template