{"id":40008366,"url":"https://github.com/guuzaa/numbers","last_synced_at":"2026-01-19T02:30:51.804Z","repository":{"id":221482973,"uuid":"753853831","full_name":"guuzaa/numbers","owner":"guuzaa","description":"C++ library to handle integer overflow","archived":false,"fork":false,"pushed_at":"2024-03-31T07:54:48.000Z","size":1035,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-16T00:45:44.535Z","etag":null,"topics":["arithmetic","cpp","cpp17-library","integer","overflow-detection"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guuzaa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2024-02-06T23:00:11.000Z","updated_at":"2024-03-15T06:10:35.000Z","dependencies_parsed_at":"2024-02-20T11:50:49.664Z","dependency_job_id":"dd8203ae-3fbe-40f7-b9f6-c742435166d8","html_url":"https://github.com/guuzaa/numbers","commit_stats":null,"previous_names":["guuzaa/numbers"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/guuzaa/numbers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guuzaa%2Fnumbers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guuzaa%2Fnumbers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guuzaa%2Fnumbers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guuzaa%2Fnumbers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guuzaa","download_url":"https://codeload.github.com/guuzaa/numbers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guuzaa%2Fnumbers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28558221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T00:46:33.223Z","status":"online","status_checked_at":"2026-01-19T02:00:08.049Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["arithmetic","cpp","cpp17-library","integer","overflow-detection"],"created_at":"2026-01-19T02:30:51.683Z","updated_at":"2026-01-19T02:30:51.788Z","avatar_url":"https://github.com/guuzaa.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\nnumbers\n\u003c/h1\u003e\n\n[![CMake CI Matrix](https://github.com/guuzaa/numbers/actions/workflows/cmake.yml/badge.svg?branch=main)](https://github.com/guuzaa/numbers/actions/workflows/cmake.yml)\n![language c++17](https://img.shields.io/badge/Language-C++17-red)\n[![license mit](https://img.shields.io/badge/License-MIT-pink)](https://github.com/guuzaa/numbers/blob/main/LICENSE.txt)\n\n`numbers` is a library for C++17 and later versions that handles integer overflow similar to Rust. It simplifies integer overflow situations.\n\n## Features\n\n- **Full Control** over handling integer overflow\n\n- **Support for Multiple Toolchains**: GCC, Clang, MSVC\n\n- **Support for Various Integer Type**: i8, i16, i32, i64, u8, u16, u32, u64, even i128 \u0026 u128\n\n## Documents\n\n\u003cdetails\u003e\n\u003csummary\u003eShow More\u003c/summary\u003e\n\n### Background\n\nWhen performing arithmetic operations in C++, handling integer overflow can be time-consuming and frustrating. To simplify this process, we have developed this library - `numbers`.\n\n### Supported Functions\n\n`numbers` provides various integer types, consisting of i8, i16, i32, i64, i128, u8, u16, u32, u64, u128.\n\nTo ease the difficulty of handling integer overflow, all integer types support the following five types of operations:\n\n1. Vanilla arithmetic operations include +, -, *, /, abs, and unary -.\n\n    If an overflow occurs, they'll throw an exception.\n\n    \u003e NOTE: The abs operator is only support by signed integers. The unsigned integers don't need the abs operation. The following abs variants adhere to the same principle.\n\n2. Checked operations include `checked_add`, `checked_sub`, `checked_div`, `checked_mul`, `checked_neg`, and `checked_abs`.\n\n    They return `std::optional` if no overflow occurs, or `std::nullopt` if an overflow occurs.\n\n3. Overflowing operations include `overflowing_add`, `overflowing_sub`, `overflowing_div`, `overflowing_mul`, `overflowing_neg`, and `overflowing_abs`.\n\n    They return a `std::tuple` of the operation result and a boolean indicating whether an overflow would occur. If an overflow would have occurred then the wrapped value is returned.\n4. Saturating operations include `saturating_add`, `saturating_sub`, `saturating_div`, `saturating_mul`, `saturating_neg`, and `saturating_abs`.\n\n    They return the saturating value at the numeric bounds instead of overflowing.\n\n    \u003e NOTE: The `saturating_neg` isn't supported by unsigned integers.\n5. Wrapping (modular) arithmetic operations include `wrapping_add`, `wrapping_sub`, `wrapping_div`, `wrapping_mul`, `wrapping_neg`, and `wrapping_abs`.\n\n    The return values of them are wrapping around at the boundary of the type.\n\n\n\u003c/details\u003e\n\n## Examples\n\n\u003cdetails\u003e\n\u003csummary\u003eShow More\u003c/summary\u003e\n\n### operator +\n```c++\nnumbers::i8 a = 100;\nstd::cout \u003c\u003c a \u003c\u003c '\\n';\ntry {\n    a = a + a;\n    std::cout \u003c\u003c a \u003c\u003c '\\n';\n} catch (std::runtime_error \u0026err) {\n    std::cout \u003c\u003c \"Catch error: \" \u003c\u003c err.what() \u003c\u003c '\\n';\n}\n```\n\n### checked sub\n```c++\nnumbers::i8 a = numbers::i8::MIN;\nstd::cout \u003c\u003c a \u003c\u003c '\\n';\nstd::optional\u003cnumbers::i8\u003e ret = a.checked_sub(1);\nif (ret) {\n    std::cout \u003c\u003c ret.value() \u003c\u003c '\\n';\n} else {\n    std::cout \u003c\u003c \"Overflow!\\n\";\n}\n```\n\n### overflowing div\n```c++\nnumbers::i16 a = 40;\nnumbers::i16 b = 2;\nauto [ret, overflowing] = a.overflowing_div(b);\nstd::cout \u003c\u003c\"a= \" \u003c\u003c a \u003c\u003c \", b= \" \u003c\u003c b \u003c\u003c '\\n';\nif (!overflowing) {\n    std::cout \u003c\u003c ret \u003c\u003c '\\n';\n} else {\n    std::cout \u003c\u003c \"Overflow!\\n\";\n}\n```\n\n### saturating mul\n```c++\nnumbers::i64 a = 40;\nnumbers::i64 b = numbers::i64::MAX;\nstd::cout \u003c\u003c \"a= \" \u003c\u003c a \u003c\u003c \", b= \" \u003c\u003c b \u003c\u003c '\\n';\nnumbers::i64 ret = a.saturating_mul(b);\nstd::cout \u003c\u003c ret \u003c\u003c '\\n';\n```\n\n### wrapping add\n```c++\nnumbers::u128 max = numbers::u128::MAX;\nnumbers::u128 ret = max.wrapping_add(1); // wrapping around\nstd::cout \u003c\u003c ret \u003c\u003c '\\n';\n```\n\u003c/details\u003e\n\n## How to build\n\u003cdetails\u003e\n\u003csummary\u003eShow More\u003c/summary\u003e\n\n### Prerequisite\n\nMake sure that `CMake` and `GCC`/`Clang`/`MSVC` are installed on your machine.\n\nThe source code, example code and test code are located in the [`src`](https://github.com/guuzaa/numbers/tree/main/src), [`examples`](https://github.com/guuzaa/numbers/tree/main/examples) and [`tests`](https://github.com/guuzaa/numbers/tree/main/tests) directory, respectively. \n\n### Generate build recipe\n\n```shell\ncmake -B build\n# If you are keen on Ninja\ncmake -B build -G Ninja\n```\n\n### Build and run all examples\n\n```shell\ncmake --build build -t example\n```\n\n#### Build and run an exact example\n\n```shell\ncmake --build build -t example-[filename]\n# If you want to run the file examples/hash.cc \ncmake --build build -t example-hash\n# If you want to run a new file you are writing in the ./examples\ncmake --build build -t example-your-file-name-with-no-extensions\n```\n\n### Build and run all tests\n\n```shell\ncmake --build build -t run-tests\n```\n\nThere are two test binaries: integer_test, uinteger_test. To run them, type the following commands:\n\n```shell\ncmake --build build -t test-integer\ncmake --build build -t test-uinteger\n```\n\n### Format code\n\n\u003e It requires that your machine has `clang-format` installed\n\n```shell\ncmake --build build -t check-format\ncmake --build build -t format\n```\n\n\u003c/details\u003e\n\n## Contribute\n\nIf you'd like to contribute, it's a good idea to discuss your plans with the project maintainers before starting work.\n\nFor the latest updates and discussions, please see our [issues](https://github.com/guuzaa/numbers/issues) and [pull requests](https://github.com/guuzaa/numbers/pulls).\n\nStay tuned for more updates, and thank you for your interest in contributing to our project!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguuzaa%2Fnumbers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguuzaa%2Fnumbers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguuzaa%2Fnumbers/lists"}