deep_causality_num/integer/
mod.rs

1/*
2 * SPDX-License-Identifier: MIT
3 * Copyright (c) 2023 - 2026. The DeepCausality Authors and Contributors. All Rights Reserved.
4 */
5
6//! Integer traits for abstracting over primitive integer types.
7//!
8//! This module provides three traits:
9//! - [`Integer`]: Common operations for all primitive integers
10//! - [`SignedInt`]: Operations specific to signed integers
11//! - [`UnsignedInt`]: Operations specific to unsigned integers
12
13mod integer_impl;
14mod signed;
15mod signed_impl;
16mod unsigned;
17mod unsigned_impl;
18
19pub use signed::SignedInt;
20pub use unsigned::UnsignedInt;
21
22use crate::Ring;
23use core::ops::{BitAnd, BitOr, BitXor, Not, Shl, Shr};
24
25/// A trait for primitive integer types.
26///
27/// This trait abstracts over both signed and unsigned integers, providing
28/// common operations and constants. It extends `Ring` from the algebraic
29/// hierarchy, reflecting that integers form a ring under addition and
30/// multiplication.
31///
32/// # Mathematical Background
33///
34/// The integers $\mathbb{Z}$ form a **Euclidean Domain**:
35/// - A commutative ring with identity
36/// - Division with remainder is well-defined: $a = bq + r$ where $0 \le r < |b|$
37/// - This enables the Euclidean algorithm for GCD
38///
39/// Fixed-width integers in computers are technically $\mathbb{Z}/2^n\mathbb{Z}$
40/// (integers modulo $2^n$), but overflow behavior varies by build configuration.
41pub trait Integer:
42    Ring
43    + Ord
44    + Copy
45    + Sized
46    + BitAnd<Output = Self>
47    + BitOr<Output = Self>
48    + BitXor<Output = Self>
49    + Not<Output = Self>
50    + Shl<u32, Output = Self>
51    + Shr<u32, Output = Self>
52{
53    /// The minimum value representable by this type.
54    const MIN: Self;
55
56    /// The maximum value representable by this type.
57    const MAX: Self;
58
59    /// The size of this type in bits.
60    const BITS: u32;
61
62    /// Returns the number of ones in the binary representation.
63    fn count_ones(self) -> u32;
64
65    /// Returns the number of zeros in the binary representation.
66    fn count_zeros(self) -> u32;
67
68    /// Returns the number of leading zeros in the binary representation.
69    fn leading_zeros(self) -> u32;
70
71    /// Returns the number of trailing zeros in the binary representation.
72    fn trailing_zeros(self) -> u32;
73
74    /// Reverses the byte order of the integer.
75    fn swap_bytes(self) -> Self;
76
77    /// Converts from big-endian to native byte order.
78    fn from_be(x: Self) -> Self;
79
80    /// Converts from little-endian to native byte order.
81    fn from_le(x: Self) -> Self;
82
83    /// Converts to big-endian byte order.
84    fn to_be(self) -> Self;
85
86    /// Converts to little-endian byte order.
87    fn to_le(self) -> Self;
88
89    /// Checked addition. Returns `None` on overflow.
90    fn checked_add(self, rhs: Self) -> Option<Self>;
91
92    /// Checked subtraction. Returns `None` on underflow.
93    fn checked_sub(self, rhs: Self) -> Option<Self>;
94
95    /// Checked multiplication. Returns `None` on overflow.
96    fn checked_mul(self, rhs: Self) -> Option<Self>;
97
98    /// Checked division. Returns `None` if `rhs == 0`.
99    fn checked_div(self, rhs: Self) -> Option<Self>;
100
101    /// Checked remainder. Returns `None` if `rhs == 0`.
102    fn checked_rem(self, rhs: Self) -> Option<Self>;
103
104    /// Saturating addition. Clamps at `MAX` or `MIN`.
105    fn saturating_add(self, rhs: Self) -> Self;
106
107    /// Saturating subtraction. Clamps at `MAX` or `MIN`.
108    fn saturating_sub(self, rhs: Self) -> Self;
109
110    /// Saturating multiplication. Clamps at `MAX` or `MIN`.
111    fn saturating_mul(self, rhs: Self) -> Self;
112
113    /// Wrapping addition. Wraps around on overflow.
114    fn wrapping_add(self, rhs: Self) -> Self;
115
116    /// Wrapping subtraction. Wraps around on underflow.
117    fn wrapping_sub(self, rhs: Self) -> Self;
118
119    /// Wrapping multiplication. Wraps around on overflow.
120    fn wrapping_mul(self, rhs: Self) -> Self;
121
122    /// Raises self to the power `exp`, using exponentiation by squaring.
123    fn pow(self, exp: u32) -> Self;
124
125    /// Calculates the quotient of Euclidean division.
126    fn div_euclid(self, rhs: Self) -> Self;
127
128    /// Calculates the remainder of Euclidean division.
129    ///
130    /// The result satisfies `0 <= r < |rhs|` for all inputs.
131    fn rem_euclid(self, rhs: Self) -> Self;
132}
deep_causality_num/integer/mod.rs

deep_causality_num/integer/
mod.rs
