README.md

numbers

numbers is a library for C++17 and later versions that handles integer overflow similar to Rust. It simplifies integer overflow situations.

Features

• Full Control over handling integer overflow

• Support for Multiple Toolchains: GCC, Clang, MSVC

• Support for Various Integer Type: i8, i16, i32, i64, u8, u16, u32, u64, even i128 & u128

Documents

Show More

Background

When performing arithmetic operations in C++, handling integer overflow can be time-consuming and frustrating. To simplify this process, we have developed this library - numbers.

Supported Functions

numbers provides various integer types, consisting of i8, i16, i32, i64, i128, u8, u16, u32, u64, u128.

To ease the difficulty of handling integer overflow, all integer types support the following five types of operations:

1. Vanilla arithmetic operations include +, -, *, /, abs, and unary -.

   If an overflow occurs, they'll throw an exception.

   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.

2. Checked operations include checked_add, checked_sub, checked_div, checked_mul, checked_neg, and checked_abs.

   They return std::optional if no overflow occurs, or std::nullopt if an overflow occurs.

3. Overflowing operations include overflowing_add, overflowing_sub, overflowing_div, overflowing_mul, overflowing_neg, and overflowing_abs.

   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.

4. Saturating operations include saturating_add, saturating_sub, saturating_div, saturating_mul, saturating_neg, and saturating_abs.

   They return the saturating value at the numeric bounds instead of overflowing.

   NOTE: The saturating_neg isn't supported by unsigned integers.

5. Wrapping (modular) arithmetic operations include wrapping_add, wrapping_sub, wrapping_div, wrapping_mul, wrapping_neg, and wrapping_abs.

   The return values of them are wrapping around at the boundary of the type.

Examples

Show More

operator +

numbers::i8 a = 100;
std::cout << a << '\n';
try {
    a = a + a;
    std::cout << a << '\n';
} catch (std::runtime_error &err) {
    std::cout << "Catch error: " << err.what() << '\n';
}

checked sub

numbers::i8 a = numbers::i8::MIN;
std::cout << a << '\n';
std::optional<numbers::i8> ret = a.checked_sub(1);
if (ret) {
    std::cout << ret.value() << '\n';
} else {
    std::cout << "Overflow!\n";
}

overflowing div

numbers::i16 a = 40;
numbers::i16 b = 2;
auto [ret, overflowing] = a.overflowing_div(b);
std::cout <<"a= " << a << ", b= " << b << '\n';
if (!overflowing) {
    std::cout << ret << '\n';
} else {
    std::cout << "Overflow!\n";
}

saturating mul

numbers::i64 a = 40;
numbers::i64 b = numbers::i64::MAX;
std::cout << "a= " << a << ", b= " << b << '\n';
numbers::i64 ret = a.saturating_mul(b);
std::cout << ret << '\n';

wrapping add

numbers::u128 max = numbers::u128::MAX;
numbers::u128 ret = max.wrapping_add(1); // wrapping around
std::cout << ret << '\n';

How to build

Show More

Prerequisite

Make sure that CMake and GCC/Clang/MSVC are installed on your machine.

The source code, example code and test code are located in the src, examples and tests directory, respectively.

Generate build recipe

cmake -B build
# If you are keen on Ninja
cmake -B build -G Ninja

Build and run all examples

cmake --build build -t example

Build and run an exact example

cmake --build build -t example-[filename]
# If you want to run the file examples/hash.cc 
cmake --build build -t example-hash
# If you want to run a new file you are writing in the ./examples
cmake --build build -t example-your-file-name-with-no-extensions

Build and run all tests

cmake --build build -t run-tests

There are two test binaries: integer_test, uinteger_test. To run them, type the following commands:

cmake --build build -t test-integer
cmake --build build -t test-uinteger

Format code

It requires that your machine has clang-format installed

cmake --build build -t check-format
cmake --build build -t format

Contribute

If you'd like to contribute, it's a good idea to discuss your plans with the project maintainers before starting work.

For the latest updates and discussions, please see our issues and pull requests.

Stay tuned for more updates, and thank you for your interest in contributing to our project!