harness_algebra/algebras/
boolean.rs

1//! # Boolean Algebra Module
2//!
3//! This module provides an implementation of the Boolean field GF(2) through a wrapper
4//! around Rust's `bool` type.
5//!
6//! ## Mathematical Structure
7//!
8//! The Boolean field consists of two elements:
9//! - `false` (0): The additive identity
10//! - `true` (1): The multiplicative identity
11//!
12//! Operations are defined as:
13//! - Addition: Exclusive OR (XOR) operation
14//! - Multiplication: Logical AND operation
15//! - Negation: Identity operation (x = -x in GF(2))
16//! - Multiplicative inverse: Identity for non-zero elements
17//!
18//! ## Algebraic Properties
19//!
20//! The implementation satisfies multiple algebraic structures:
21//! - Field: A complete algebraic field with addition and multiplication
22//! - Abelian Group: Under addition with identity element `false`
23//! - Vector Space: Over itself as the scalar field
24//!
25//! ## Applications
26//!
27//! Boolean algebra has numerous applications in:
28//! - Digital circuit design
29//! - Logic operations
30//! - Cryptography (especially in finite field arithmetic)
31//! - Error correction codes
32//!
33//! ## Example
34//!
35//! ```
36//! use harness_algebra::algebras::boolean::Boolean;
37//!
38//! // Create Boolean values
39//! let a = Boolean(true); // 1
40//! let b = Boolean(false); // 0
41//!
42//! // Addition (XOR)
43//! assert_eq!(a + a, Boolean(false)); // 1 + 1 = 0
44//! assert_eq!(a + b, Boolean(true)); // 1 + 0 = 1
45//!
46//! // Multiplication (AND)
47//! assert_eq!(a * b, Boolean(false)); // 1 * 0 = 0
48//! assert_eq!(a * a, Boolean(true)); // 1 * 1 = 1
49//! ```
50
51use super::*;
52
53/// A wrapper around `bool` that implements algebraic operations.
54///
55/// This type implements both [`Additive`] and [`Multiplicative`] traits using
56/// bitwise operations:
57/// - Addition is implemented as XOR (`^`)
58/// - Multiplication is implemented as AND (`&`)
59///
60/// This makes `Boolean` a field with two elements, where:
61/// - `false` is the additive identity (0)
62/// - `true` is the multiplicative identity (1)
63///
64/// # Examples
65///
66/// ```
67/// use harness_algebra::algebras::boolean::Boolean;
68///
69/// let a = Boolean(true);
70/// let b = Boolean(false);
71///
72/// // Addition (XOR)
73/// assert_eq!(a + b, Boolean(true));
74/// assert_eq!(a + a, Boolean(false)); // a + a = 0
75///
76/// // Multiplication (AND)
77/// assert_eq!(a * b, Boolean(false));
78/// assert_eq!(a * a, Boolean(true)); // a * a = a
79/// ```
80#[derive(Copy, Clone, Debug, PartialEq, Eq)]
81pub struct Boolean(pub bool);
82
83impl From<bool> for Boolean {
84  fn from(b: bool) -> Self { Self(b) }
85}
86
87impl From<Boolean> for bool {
88  fn from(b: Boolean) -> Self { b.0 }
89}
90
91impl One for Boolean {
92  fn one() -> Self { Self(true) }
93}
94
95impl Zero for Boolean {
96  fn zero() -> Self { Self(false) }
97
98  fn is_zero(&self) -> bool { !self.0 }
99}
100
101impl Add for Boolean {
102  type Output = Self;
103
104  /// Implements addition as XOR operation.
105  ///
106  /// This corresponds to the addition operation in the field GF(2).
107  #[allow(clippy::suspicious_arithmetic_impl)]
108  fn add(self, rhs: Self) -> Self::Output { Self(self.0 ^ rhs.0) }
109}
110
111impl Sub for Boolean {
112  type Output = Self;
113
114  #[allow(clippy::suspicious_arithmetic_impl)]
115  fn sub(self, rhs: Self) -> Self::Output { self + rhs }
116}
117
118impl Neg for Boolean {
119  type Output = Self;
120
121  fn neg(self) -> Self::Output { self }
122}
123
124impl SubAssign for Boolean {
125  /// Implements subtraction assignment as XOR operation.
126  #[allow(clippy::suspicious_op_assign_impl)]
127  fn sub_assign(&mut self, rhs: Self) { self.0 ^= rhs.0; }
128}
129
130impl AddAssign for Boolean {
131  /// Implements addition assignment as XOR operation.
132  #[allow(clippy::suspicious_op_assign_impl)]
133  fn add_assign(&mut self, rhs: Self) { self.0 ^= rhs.0; }
134}
135
136impl Mul for Boolean {
137  type Output = Self;
138
139  /// Implements multiplication as AND operation.
140  ///
141  /// This corresponds to the multiplication operation in the field GF(2).
142  fn mul(self, rhs: Self) -> Self::Output { Self(self.0 && rhs.0) }
143}
144
145impl MulAssign for Boolean {
146  /// Implements multiplication assignment as AND operation.
147  #[allow(clippy::suspicious_op_assign_impl)]
148  fn mul_assign(&mut self, rhs: Self) { self.0 &= rhs.0; }
149}
150
151impl Div for Boolean {
152  type Output = Self;
153
154  #[allow(clippy::suspicious_arithmetic_impl)]
155  fn div(self, rhs: Self) -> Self::Output { self * rhs }
156}
157
158impl DivAssign for Boolean {
159  /// Implements division assignment as AND operation.
160  #[allow(clippy::suspicious_op_assign_impl)]
161  fn div_assign(&mut self, rhs: Self) { self.0 &= rhs.0; }
162}
163
164impl Additive for Boolean {}
165impl Multiplicative for Boolean {}
166
167impl groups::Group for Boolean {
168  fn identity() -> Self { Self(false) }
169
170  fn inverse(&self) -> Self { Self(!self.0) }
171}
172
173impl groups::AbelianGroup for Boolean {}
174
175impl rings::Ring for Boolean {}
176
177impl rings::Field for Boolean {
178  fn multiplicative_inverse(&self) -> Self { *self }
179}
180
181impl modules::LeftModule for Boolean {
182  type Ring = Self;
183}
184
185impl modules::RightModule for Boolean {
186  type Ring = Self;
187}
188
189impl modules::TwoSidedModule for Boolean {
190  type Ring = Self;
191}
192
193impl modules::VectorSpace for Boolean {}
harness_algebra/algebras/boolean.rs

harness_algebra/algebras/
boolean.rs
