{"id":22747662,"url":"https://github.com/stefanhamminga/saturating","last_synced_at":"2025-04-12T22:41:49.787Z","repository":{"id":49666588,"uuid":"109012229","full_name":"StefanHamminga/saturating","owner":"StefanHamminga","description":"C++ header only library for saturation arithmetic functions and always saturating types.","archived":false,"fork":false,"pushed_at":"2021-06-11T06:27:14.000Z","size":33,"stargazers_count":16,"open_issues_count":2,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-26T16:48:58.355Z","etag":null,"topics":["arithmetic","cpp","library","saturating-functions","saturation","saturation-arithmetic","template"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StefanHamminga.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}},"created_at":"2017-10-31T15:04:11.000Z","updated_at":"2024-05-19T20:16:24.000Z","dependencies_parsed_at":"2022-09-01T11:51:41.670Z","dependency_job_id":null,"html_url":"https://github.com/StefanHamminga/saturating","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StefanHamminga%2Fsaturating","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StefanHamminga%2Fsaturating/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StefanHamminga%2Fsaturating/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StefanHamminga%2Fsaturating/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StefanHamminga","download_url":"https://codeload.github.com/StefanHamminga/saturating/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248643045,"owners_count":21138353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["arithmetic","cpp","library","saturating-functions","saturation","saturation-arithmetic","template"],"created_at":"2024-12-11T03:16:49.992Z","updated_at":"2025-04-12T22:41:49.766Z","avatar_url":"https://github.com/StefanHamminga.png","language":"C++","readme":"# C++ saturating arithmetic functions and types\nC++ header only library for always saturating functions and types.\nFor a quick introduction to saturation arithmetic take a look at the [Wikipedia](https://en.wikipedia.org/wiki/Saturation_arithmetic) page.\n\n## Description\n\nThe library features two entry points: [`functions.hpp`](https://github.com/StefanHamminga/saturating/blob/master/functions.hpp) and [`types.hpp`](https://github.com/StefanHamminga/saturating/blob/master/types.hpp).\n\n### functions.hpp\nThe functions header provides the namespace `saturating` containing `add`, `subtract`, `multiply`, and `divide`, each taking two arguments and returning a _plain_ value of a type that can fit either argument. Simplified this comes down to a combination of promotion to signed or floating point, and increasing the type size. The library aims to remove as many type conversions pitfalls as possible. This includes avoiding unintended `int` =\u003e `unsigned` promotions and properly rounding floating point results back to integrals.\n\nSeveral smaller utility functions are provided in the namespace, for a quick overview check [`utilities.hpp`](https://github.com/StefanHamminga/saturating/blob/master/utilities.hpp)\n\n### types.hpp\n\nThis header includes the above functions header and extends this to provide the `saturating::type` template class, allowing to create automatically saturating types. The types use saturating operators by default, but returning saturating types where possible, allowing saturation to be respected throughout a chain of operations.\n\nSeveral `std` namespaced functions, like `std::is_arithmetic` or `std::numeric_limits\u003cT\u003e` are specialized to integrate saturating types more seamlessly.\n\nThe following default integral types are introduced to the global namespace:\n\n```cpp\nint_sat8_t;\nuint_sat8_t;\n\nint_sat16_t;\nuint_sat16_t;\n\nint_sat32_t;\nuint_sat32_t;\n\nint_sat64_t;\nuint_sat64_t;\n\n// If 128 bit integers are supported:\nint_sat128_t;\nuint_sat128_t;\n\n// And these floating point types, if their primitives are available:\n\nfloat_sat_t;\ndouble_sat_t;\nlong_double_sat_t;\n```\n\nThis functionality can be disabled by defining `SATURATING_TYPES_h_NO_GLOBALS`.\n\nCustom types can be created using the universal template:\n\n```cpp\n// Standard declaration: -128, …, 127\ntypedef saturating::type\u003cint8_t\u003e int_sat8_t;\n\n// Custom lower limit: -127, …, 127\ntypedef saturating::type\u003cint8_t, -127\u003e custom1_t;\n\n// Custom limit: 16, …, 32\ntypedef saturating::type\u003cint8_t, 16, 32\u003e custom2_t;\n\n// Floating points have a default -1 … 1 range, but can take any integral limits\ntypedef saturating::type\u003cdouble, -10, 10\u003e custom3_t;\n\n```\n\n## Dependencies\n\nOther than a modern C++17 compiler this library depends on:\n\n- [arithmetic_type_tools](https://github.com/StefanHamminga/arithmetic_type_tools) - Tools used to manage the required type upgrades.\n- [cpp_lib_scripts](https://github.com/StefanHamminga/cpp_lib_scripts) - Automate building and installation.\n\n## Usage example\n\nIf you want to install the libraries systems wide (Linux) do:\n\n```bash\ngit clone https://github.com/StefanHamminga/saturating saturating\ncd saturating\nmkdir build\ncd build/\n\ncmake -DCMAKE_INSTALL_PREFIX=/usr ..\n\n# Optionally run the tests\nmake check\n\nsudo make install\n\n# Libraries are now available as:\n# #include \u003csaturating/functions.hpp\u003e\n# or\n# #include \u003csaturating/types.hpp\u003e\n```\n\nA small example C++ source:\n\n```cpp\n#include \u003ccstddef\u003e\n#include \u003ccstdint\u003e\n#include \"saturating/types.hpp\"\n\nuint8_t x[] { 101, 27, 3, 95 };\n\nint main () {\n    uint_sat8_t s = 25;\n\n    for (const auto\u0026 v : x) {\n        s -= v;\n    } // s == 0\n    s++; // s == 1\n    for (const auto\u0026 v : x) {\n        s *= v;\n    }\n\n    volatile unsigned j = s; // s == 255\n}\n```\n\n### Tests\n\nRun `make check` to build and run the test program.\n\n## License, author, contributors\n\nThe saturated types library is written by [Stefan Hamminga](stefan@prjct.net), with contributions by [Toby Speight](https://codereview.stackexchange.com/questions/179172/c17-saturating-integer-arithmetic-type-library).\n\nThis work is released under the terms of the Apache 2.0 license. The complete text is included in the `LICENSE` file.\n\n## Repository\n\n[saturating (GitHub)](https://github.com/StefanHamminga/saturating)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanhamminga%2Fsaturating","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefanhamminga%2Fsaturating","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanhamminga%2Fsaturating/lists"}