1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
use crateInteger;
/// # Circle
///
/// Circles represents complex numbers using two's complement real and imaginary components with a shared exponent and customizable precision/range.
///
/// ## Type Parameters
///
/// - `F`: Fraction - Any sized Rust signed integer type (i8, i16, i32, i64, i128)
/// - `E`: Exponent - Any sized Rust signed integer type (i8, i16, i32, i64, i128)
///
/// ## Representation
///
/// Circles use a normalized representation where components share the same exponent:
/// `(real + imaginary*i) * 2^exponent` for normal numbers, with specific bit patterns for:
///
/// - Normal finite numbers `[#]` (with positive and negative components)
/// - Exploded values `[↑]` (numbers too large to represent)
/// - Vanished values `[↓]` (numbers too small to represent)
/// - Actual Zero `[0]`
/// - Singular Infinity `[∞]`
/// - Undefined states `[℘]`
///
/// ## Normalization Levels
///
/// The bit patterns in the real and imaginary components follow these normalization levels:
///
/// ```txt
/// Position: 01234567...
///
/// N0: Zero and Infinity
/// □□□□□□□□ Zero [0]
/// ■■■■■■■■ Infinity [∞]
///
/// N1: Normal and Exploded Values
/// □■xxxxxx | ■□xxxxxx Normal [#,#] or exploded [↑]
///
/// N2: Vanishing Values
/// □□■xxxxx | ■■□xxxxx Vanished [↓]
///
/// N3+: Undefined States
/// □□□xxxxx | ■■■xxxxx
/// ```
///
/// See `undefined.rs` for the complete catalog of undefined patterns.
///
/// ## Mathematical Properties
///
/// Circles maintain consistent behavior across operations:
///
/// - The shared exponent applies to both fractions
/// - When the exponent goes out of range, values "escape" to exploded (almost ∞) or vanished (almost 0) states while preserving angular orientation
/// - Undefined states stay fixed thru subsequent operations
/// - Complex operations like addition, multiplication, and division work with Circles, Scalars and Rust primitives
/// - Distinct modulus (%) and modulo (.modulo()) operations are provided for mathematical vs programming applications
///
/// ## Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E3};
///
/// // Create a Circle with 32-bit components and 8-bit exponent from a tuple (R,I)
/// let z = Circle::<i32, i8>::from((1.5, 2));
///
/// // Using a type alias for the same size with no real component
/// let w = CircleF5E3::from((0, -16.8));
///
/// // Using a single real component
/// let d = CircleF5E3::from(2.2);
///
/// // Basic arithmetic
/// let sum = z + w;
/// let product = d * w;
///
/// // Basic arithmetic with primitives
/// let sum = z + 42;
/// let product = w.pow(d) * -44.25;
/// let reciprocal = 1 / d;
///
/// // Complex-specific operations
/// let conj = sum.conjugate();
/// let magnitude = product.magnitude();
///
/// // Infinity is a singular entity in Spirix
/// let infinite = z / 0;
/// assert!(infinite.is_infinite());
/// ```