{"id":49569798,"url":"https://github.com/mcpplibs/primitives","last_synced_at":"2026-05-03T13:11:40.570Z","repository":{"id":344220991,"uuid":"1180485170","full_name":"mcpplibs/primitives","owner":"mcpplibs","description":"A library based on C++23 that encapsulates primitives types","archived":false,"fork":false,"pushed_at":"2026-04-01T10:55:05.000Z","size":599,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T12:34:37.646Z","etag":null,"topics":["c-plus-plus","integer-arithmetic","safety-critical","type-safety"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcpplibs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-13T04:55:48.000Z","updated_at":"2026-04-01T10:55:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mcpplibs/primitives","commit_stats":null,"previous_names":["mcpplibs/primitives"],"tags_count":4,"template":false,"template_full_name":"mcpplibs/templates","purl":"pkg:github/mcpplibs/primitives","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpplibs%2Fprimitives","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpplibs%2Fprimitives/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpplibs%2Fprimitives/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpplibs%2Fprimitives/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcpplibs","download_url":"https://codeload.github.com/mcpplibs/primitives/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcpplibs%2Fprimitives/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32569919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","integer-arithmetic","safety-critical","type-safety"],"created_at":"2026-05-03T13:11:39.520Z","updated_at":"2026-05-03T13:11:40.565Z","avatar_url":"https://github.com/mcpplibs.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcpplibs primitives\n\n\u003e C++23 modular primitives library - `import mcpplibs.primitives;`\n\n[![d2x](https://img.shields.io/badge/d2x-ok-green.svg)](https://github.com/d2learn/d2x)\n[![Online-ebook](https://img.shields.io/badge/online-ebook-orange.svg)](https://github.com/d2learn/d2x)\n[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE-CODE)\n\n| [中文](README.zh.md) - [English](README.md) - [Forum](https://mcpp.d2learn.org/forum) |\n|---------------------------------------------------------------------------------|\n| [用户文档](docs/guide/zh/README.md) - [User Documentation](docs/guide/en/README.md) |\n| [API文档](docs/api/zh/README.md) - [API Documentation](docs/api/en/README.md)  |\n\nThis repository provides configurable `primitive` infrastructure (`underlying traits`, `policy`, and `operations/dispatcher`) to unify numeric behavior, error handling, and concurrency access semantics.\n\n\u003e [!WARNING]\n\u003e The project is still evolving quickly, and APIs may change.\n\n## Features\n\n- **C++23 modules** — `import mcpplibs.primitives;`\n- **Dual build systems** — both xmake and CMake are supported\n- **Policy-driven behavior** — value/type/error/concurrency policies are composable\n- **Mixed operations support** — binary operations between `primitive` and `underlying` are supported\n- **Concurrency access APIs** — `primitive::load/store/compare_exchange`\n\n## Operators\n\nThe library provides unary, arithmetic, bitwise, and comparison operations for `primitive`.  \nArithmetic paths are dispatched through a unified pipeline and return `std::expected\u003c..., policy::error::kind\u003e`.\n\n- Value policies (`policy::value::checked` / `policy::value::saturating` / `policy::value::unchecked`) define overflow behavior.\n- Error policies (`policy::error::throwing` / `policy::error::expected` / `policy::error::terminate`) define how errors are propagated.\n\nExample:\n\n```cpp\nimport std;\nimport mcpplibs.primitives;\n\nusing namespace mcpplibs::primitives;\nusing namespace mcpplibs::primitives::operators;\n\nprimitive\u003cint\u003e a{1};\nprimitive\u003cint\u003e b{2};\nauto sum = a + b; // std::expected\u003cprimitive\u003cint\u003e, policy::error::kind\u003e\n\nusing checked_t =\n    primitive\u003cint, policy::value::checked, policy::error::expected\u003e;\nauto maybe_overflow =\n    checked_t{std::numeric_limits\u003cint\u003e::max()} + checked_t{1};\n```\n\n## Policy Protocol Namespaces\n\nWhen implementing custom policies, protocol entry points are split by responsibility:\n\n- `policy::type::handler` / `policy::type::handler_available`\n- `policy::concurrency::handler` / `policy::concurrency::injection`\n- `policy::value::handler` / `policy::value::decision`\n- `policy::error::handler` / `policy::error::request` / `policy::error::kind`\n\nBuilt-in policy tags:\n\n- `policy::value::{checked, unchecked, saturating}`\n- `policy::type::{strict, compatible, transparent}`\n- `policy::error::{throwing, expected, terminate}`\n- `policy::concurrency::{none, fenced, fenced_relaxed, fenced_acq_rel, fenced_seq_cst}`\n\nConcurrency notes:\n\n- `fenced*` policies provide operation-level concurrency semantics with injected memory-order fences.\n- `primitive` storage keeps a uniform, zero-extra-storage abstraction.\n- `primitive::load/store/compare_exchange` are provided by concurrency policy protocols and fail at compile time if unsupported.\n\nExample (concurrent access APIs):\n\n```cpp\nusing shared_t = primitive\u003cint, policy::value::checked,\n                           policy::concurrency::fenced_acq_rel,\n                           policy::error::expected\u003e;\n\nshared_t v{1};\nv.store(2);\nauto expected = 2;\nif (v.compare_exchange(expected, 3)) {\n  auto now = v.load();\n  (void)now;\n}\n```\n\nDefault policies are available under `policy::defaults`:\n\n- `policy::defaults::value`\n- `policy::defaults::type`\n- `policy::defaults::error`\n- `policy::defaults::concurrency`\n\n## Examples\n\n- `ex01_basic_usage`: Literals + primitive factory helpers with the built-in operator set.\n- `ex02_type_policy`: Type negotiation with `strict/compatible`, including how type policy affects construction from `underlying`.\n- `ex03_value_policy`: `checked/unchecked/saturating` behavior, including mixed binary operations with `underlying`.\n- `ex04_error_policy`: Error-handling behavior across different error policies.\n- `ex05_concurrency_policy`: Representative mixed read/write concurrency workload (writer `store` + reader `add/sub` + `CAS`).\n- `ex06_conversion`: Checked/saturating/truncating/exact conversion helpers across underlying values and primitives.\n- `ex07_algorithms`: Limits metadata, special numeric values, and hashing helpers.\n- `ex08_custom_underlying`: Custom underlying traits, rep validation, and common-rep extension.\n- `ex09_custom_policy`: Custom policy protocol implementation.\n- `ex10_custom_operation`: Custom operation extension.\n\n## Project Layout\n\n```\nmcpplibs-primitives/\n├── src/                        # module sources\n│   ├── primitives.cppm         # top-level aggregate module\n│   ├── primitive/              # primitive definitions and traits\n│   ├── policy/                 # policy tags and protocol implementations\n│   ├── operations/             # operation tags / dispatcher / operators\n│   └── underlying/             # underlying traits and common_rep\n├── examples/                   # example programs\n├── tests/                      # test entry and basic test suite\n├── xmake.lua                   # xmake build script\n├── CMakeLists.txt              # CMake build script\n└── .xlings.json                # xlings package descriptor\n```\n\n## Quick Start\n\n```cpp\nimport std;\nimport mcpplibs.primitives;\n\nint main() {\n  using namespace mcpplibs::primitives;\n\n  using value_t = primitive\u003cint, policy::error::expected\u003e;\n  auto const result = operations::add(value_t{40}, value_t{2});\n  return (result.has_value() \u0026\u0026 result-\u003evalue() == 42) ? 0 : 1;\n}\n```\n\n## Installation and Setup\n\n```bash\nxlings install\n```\n\n## Build and Run\n\n**Using xmake**\n\n```bash\nxmake build mcpplibs-primitives\nxmake run basic                    # compatibility alias for ex01_basic_usage\nxmake run ex01_basic_usage\nxmake run ex06_conversion\nxmake run ex07_algorithms\nxmake run ex05_concurrency_policy\nxmake run primitives_test\n```\n\n**Using CMake** (`CMake \u003e= 3.31`)\n\n```bash\ncmake -B build -G Ninja\ncmake --build build --target mcpplibs-primitives\ncmake --build build --target ex01_basic_usage\ncmake --build build --target ex06_conversion\ncmake --build build --target ex07_algorithms\ncmake --build build --target basic_tests\nctest --test-dir build --output-on-failure\n```\n\n## Build System Integration\n\n### xmake\n\n```lua\nadd_repositories(\"mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git\")\n\nadd_requires(\"primitives\")\n\ntarget(\"myapp\")\n    set_kind(\"binary\")\n    set_languages(\"c++23\")\n    add_files(\"main.cpp\")\n    add_packages(\"primitives\")\n    set_policy(\"build.c++.modules\", true)\n```\n\n## Related Links\n\n- [mcpp-style-ref | Modern C++ coding and project style reference](https://github.com/mcpp-community/mcpp-style-ref)\n- [d2mystl | Build a mini STL from scratch](https://github.com/mcpp-community/d2mystl)\n- [mcpp community website](https://mcpp.d2learn.org)\n- [mcpp forum](https://mcpp.d2learn.org/forum)\n- [Getting Started: Learn Modern C++ by Building](https://github.com/Sunrisepeak/mcpp-standard)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcpplibs%2Fprimitives","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcpplibs%2Fprimitives","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcpplibs%2Fprimitives/lists"}