Unsigned Integer Types

Overview

The library provides safe unsigned integer types that detect overflow, underflow, and other undefined behavior at runtime. These types are drop-in replacements for the standard unsigned integer types with added safety guarantees.

Available Types

The following types are provided in the boost::safe_numbers namespace:

namespace boost::safe_numbers {

using u8   = detail::unsigned_integer_basis<std::uint8_t>;
using u16  = detail::unsigned_integer_basis<std::uint16_t>;
using u32  = detail::unsigned_integer_basis<std::uint32_t>;
using u64  = detail::unsigned_integer_basis<std::uint64_t>;
using u128 = detail::unsigned_integer_basis<int128::uint128_t>;

} // namespace boost::safe_numbers

Each type exposes a basis_type member type alias that refers to the underlying integer type, allowing conversion back to built-in types when needed.

Construction

Default Construction

Values are default-initialized to zero.

Explicit Construction from Underlying Type

Construction from the underlying type is explicit to prevent accidental conversions.

Construction from bool is Prohibited

Constructing from bool is a compile-time error.

Type Conversions

Explicit Conversion to Underlying Types

Conversion to other unsigned integral types is explicit.

Narrowing Conversions are Prohibited

Narrowing conversions cause a compile-time error.

Comparison Operators

Full three-way comparison is supported via operator<⇒, which returns std::strong_ordering. All comparison operators (<, ⇐, >, >=, ==, !=) are available.

Arithmetic Operators

All arithmetic operators perform runtime checks and throw exceptions when undefined behavior would occur.

Addition (operator+, operator+=)

Throws std::overflow_error if the result would exceed the maximum representable value.

Subtraction (operator-, operator-=)

Throws std::underflow_error if the result would be negative (wrap around).

Multiplication (operator*, operator*=)

Throws std::overflow_error if the result would exceed the maximum representable value.

Division (operator/, operator/=)

Throws std::domain_error if dividing by zero.

Modulo (operator%, operator%=)

Throws std::domain_error if the divisor is zero.

Increment and Decrement Operators

Pre-increment and Post-increment (++)

Throws std::overflow_error if the value is already at the maximum.

Pre-decrement and Post-decrement (--)

Throws std::underflow_error if the value is already zero.

Mixed-Width Operations are Prohibited

Operations between different width safe integer types are compile-time errors. To perform operations between different widths, explicitly convert to the same type first.

Saturating Arithmetic

For cases where throwing exceptions is not desired, saturating arithmetic functions are provided. These functions clamp the result to the representable range instead of throwing.

add_sat

Returns the sum of two values, saturating at the maximum value on overflow.

Exception Summary

Operation Exception Type Condition

`, `=

std::overflow_error

Result exceeds maximum value

-, -=

std::underflow_error

Result would be negative

, =

std::overflow_error

Result exceeds maximum value

/, /=

std::domain_error

Division by zero

%, %=

std::domain_error

Modulo by zero

++ (pre/post)

std::overflow_error

Value is at maximum

-- (pre/post)

std::underflow_error

Value is zero

Constexpr Support

All operations are constexpr-compatible when evaluated at compile time. Overflow at compile time results in a compile error.

Edit this Page