From 5302fc3481b600d2f22007d2045c4783a414a981 Mon Sep 17 00:00:00 2001 From: guza Date: Sun, 31 Mar 2024 15:46:36 +0800 Subject: [PATCH] update README description --- CMakeLists.txt | 2 +- README.md | 20 ++++++++++++-------- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 88f743b..4c108a3 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -87,7 +87,7 @@ if(NUMBERS_TEST) ) # Provide only the minimum source files needed by downstream users - set(package_files src/ CMakeLists.txt LICENSE.txt) + set(package_files src/ CMakeLists.txt README.md LICENSE.txt) set(packaged_zip ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}-src.zip) add_custom_command( OUTPUT ${packaged_zip} diff --git a/README.md b/README.md index 28a334e..ea27cc3 100644 --- a/README.md +++ b/README.md @@ -21,33 +21,37 @@ numbers
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`. -`numbers` provides various integer types, consisting of i8, i16, i32, i64, i128, u8, u16, u32, u64, u128. All types are defined in `numbers` namespace, which lives in `numbers.h`. +### 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, `numbers` supports five kinds of operations: +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 -. - Different from these operators of primitive types, if an overflow occurs, they'll throw an exception. + 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 to perform the abs operation. The following abs variants adhere to the same principle. + > 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`. - These operators return `std::optional` if no overflow occurs, or `std::nullopt` if an overflow does occur. + 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`. - These operators 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. + 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`. - These operators return the saturating value at the numeric bounds instead of overflowing. + 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 these operators are wrapping around at the boundary of the type. + The return values of them are wrapping around at the boundary of the type.